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Special Notices 


The licensed program described in this document and all licensed material avail- 
able for it are provided by IBM under terms of the Agreement for IBM Licensed Pro- 
grams. Changes are made periodically to the information herein; before you use 
this document in connection with the operation of IBM systems, consult the latest 
IBM System/370, 30XX, 4300, and 9370 Processors Bibliography, GC20-0001, for the 
editions that are applicable and current. 


Any reference to an IBM licensed program in this document is not intended to state 
or imply that only IBM’s program may be used. 


This book contains product-sensitive programming interfaces for customers pro- 
vided by VTAM. Installation exits and other product-sensitive interfaces are pro- 
vided to allow the customer installation to perform tasks such as product tailoring, 
monitoring, modification, or diagnosis. They are dependent on the detailed design 
or implementation of the product. Such interfaces should be used only for these 
specialized purposes. Because of their dependencies on detailed design and imple- 
mentation, it is to be expected that programs written to such interfaces may need to 
be changed in order to run with new product releases or versions, or as a result of 
service. 


IBM may have patents or pending patent applications covering subject matter 
described in this document. Furnishing of this document does not give you any 
license to these patents. You can send inquiries, in writing, to the IBM Director of 
Commercial Relations, International Business Machines Corporation, Purchase, 
New York, 10577. 


Licenses under IBM’s utility patents are available on reasonable and 
nondiscriminatory terms and conditions. IBM does not grant licenses under its 
appearance design patents. Inquiries relative to licensing should be directed in 
writing to the IBM Director of Commercial Relations, International Business 
Machines Corporation, Armonk, New York, 10504. 


References in this publication to IBM products, programs, or services do not imply 
that IBM intends to make them available in all countries in which IBM operates. 


This document is not intended for production use and is furnished as is without any 
warranty of any kind, and all warranties are hereby disclaimed including the war- 
ranties of merchantability and fitness for a particular purpose. 


Some trademarks of the IBM Corporation in the United States and/or other countries 
appear in this document. These IBM trademarks are: 
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About This Book 


Customization is the process of tailoring VTAM- by enhancing or extending it to suit 
your needs. VTAM Customization is a reference book for programmers responsible 
for customizing VTAM. 


vm VSCS, although it is shipped with VTAM, is an application program. Therefore, 
this book discusses VSCS separately from VTAM. 


Note: VM/9370 VTAM can be installed only on the following IBM" Enterprise 
systems/9370 models running under a VM/SP operating system: 


¢ 9371 
¢ 9373 
e 9375 
e 9377. 


Who Should Use This Book 


Your job title probably includes the word “system programmer” or “analyst.” Use 
this book if your job includes customizing VTAM. Before using this book, you should 
be familiar with the information in the following publications: 


e Planning and Reference for NetView, NCP and VTAM 
¢ VTAM Network Implementation Guide 
e VTAM Resource Definition Reference. 


How to Use This Book 


You can use this book as a reference for customizing VTAM to meet your own 
needs. It can also be used as background reading to help understand the uses and 
function of exit routines and VTAM constants. Definitions of technical terms are in 
the “Glossary” on page 141. 


How This Book Is Organized 


VTAM Customization consists of four chapters and two appendixes: 


e Chapter 1, “Writing VTAM Exit Routines” on page 3, describes how to code and 
install VTAM exit routines, including: 


— Session management exit routine 

— Virtual route selection exit routine 

— VR pacing window size calculation exit routine 
— Session accounting exit routine 

— Session authorization exit routine 

— vse TPRINT processing exit routine. 


Trademark of the IBM Corporation. See “Special Notices” on page iii for a list of all IBM trademarks used in this book. 
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e Chapter 2, “Defining User Modules and Tables” on page 69, describes how to 
create and modify the communication network management (CNM) table and 
VTAM modules. It also discusses installing tables and modules in VM, and 
logon-interpret routine requirements. 


¢ Chapter 3, “Writing VSCS Exit Routines for VM" on page 93, describes how to 
code and install VSCS data manipulation exit routines. 


e Chapter 4, “Writing TSO/VTAM Exit Routines for MVS” on page 101, provides 
information you will need to write and install exit routines for TSO/VTAM. 


e Appendix A, “IBM-Supplied CNM Routing Table” on page 111, lists the 
IBM-supplied CNM table. 


e Appendix B, “Sample Session Management Exit Routine” on page 113, illus- 
trates how the initial session management exit routine environment is estab- 
lished, the type of information available in each parameter list for the specific 
sample environment, and some techniques used to examine the various param- 
eter lists. 


Symbols Used in This Book 


The following symbols are used in this book to indicate information that pertains toa 
specific operating system: 


MVS/XA Indicates information that applies to MVS/XA only. It is not used 
in this manual, because this manual contains no information that is 
unique to MVS/XA. 


MVS/ESA Indicates information that applies to MVS/ESA * only. 

MVS Indicates information that applies to both MVS/XA and MVS/ESA, 
but not VM or VSE. 

VM Indicates information that applies to VM only. 

VM/ESA Indicates information that applies to VM/ESA only. 

VSE Indicates information that applies to VSE only. 


Note: Because VSE/ESA is one of the licensed programs in 
VSE/System Package, no distinction is made between the two. 


ES/9370 Indicates information that applies only to the telecommunications 
subsystem controller, the token-ring subsystem controller, or the 
workstation subsystem controller on the Enterprise System/9370 
processor supported by the VM or VSE operating system only. 


These symbols precede unique information. If a piece of information applies to 
more than one operating system, but not all of them, more than one symbol can 


precede the information. For example: 


mvs vM This function locates the resource in this network or another network associ- 
ated with a given symbolic name or network address. 


The information in the example applies to MVS/XA, MVS/ESA, and VM, but not VSE. 
Information that applies to all operating systems is not denoted by any symbol. 


* 
Trademark of the IBM Corporation. See “Special Notices” on page iii for a list of all IBM trademarks used in this book. 
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What Is New in This Book 


Version 3 Release 3 for VM/ESA 


VTAM Version 3 Release 3 for VM/ESA uses System 370/XA architecture to take 
advantage of 31-bit addressable storage. VTAM uses 31-bit addressable storage as 
much as possible to provide more space (beyond 24-bit addressable storage) for 
VTAM and customer application programs. This reduces the demand for 24-bit 
addressable storage and eases storage constraints on the members of a Group 
Control System (GCS) group. See “Installing VTAM Exit Routines” on page 66 and 
Chapter 2, “Defining User Modules and Tables” on page 69 for more information on 
VM/ESA. 


Session Management Exit Enhancements 


mvs VM Alias Selection Function 
In V3R3, you can use the session management exit routine to translate session 
information. You can use this function to replace or complement NetView’s alias 
application. See pages 17 and 33 for more information on this function. 


Initial Authorization Function Enhancement 
This function allows network providers to authorize new sessions that are requested 
by application programs passing sessions from one partner to another using the 
CLSDST OPTCD=PASS macroinstruction. See page 10 for more information on this 
function. 


Dynamic Adjacent SSCP Tables 


You no longer need to code adjacent SSCP tables to establish cross-domain or 
cross-network sessions. You can now use the DYNASSCP start option and VTAM 
will route session establishment requests dynamically. See page 15 for more infor- 
mation on this function. 


Other Changes, Additions, and Deletions 


Constants 
MVS/ESA Three new constants are added to the constants module (ISTRACON): 


RACSAWLM SAW data space limit factor (page 84) 
RACSAWPK SAW data space packing factor (page 84) 
RACPIULM PIU data space limit factor (page 84). 


VSE The constant RACCPS for X.21 CPS retry is removed from the constants module. 


Sample Session Management Exit Routine 
Appendix B, “Sample Session Management Exit Routine” on page 113, illustrates 
how the initial session management exit routine environment is established, the 
type of information available in each parameter list for the specific sample environ- 
ment, and some techniques used to examine the various parameter lists. 
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Where to Find More Information 


Table 1 shows the books in the VTAM V3R3 library, arranged according to related 
tasks. For a description of these manuals, see “Bibliography” on page 165. The 
bibliography also lists the titles and order numbers of manuals related to this 


manual or cited by name in this manual. 


Table 1. The VTAM V3R8 Library 


Planning 

$C31-6092 
GC31-6429 
SK2T-2010 


Planning and Reference for NetView, NCP, and VTAM 
VTAM Directory of Migration Information 
VTAM Storage Estimates (diskette only) 


installation and Resource Definition 


$C31-6404 
$C31-6412 


Customization 
LY 43-0046 


Operation 
$C31-6408 
$C31-6405 


VTAM Network Implementation Guide 
VTAM Resource Definition Reference 


VTAM Customization 


VTAM Operation 
VTAM Messages and Codes 


Writing Application Programs 


$C31-6409 
SC31-6410 


Diagnosis 
LY43-0042 
LY43-0053 (V3R3) 
LY43-0043 (V3R3) 
LY43-0045 (V3R3) 


Reference 


LY43-0047 
GC31-6430 


VTAM Customization 


VTAM Programming 
VTAM Programming for LU 6.2 


VTAM Diagnosis 

VTAM Data Areas for VSE 
VTAM Data Areas for MVS 
VTAM Data Areas for VM 


VTAM Reference Summary 
Bibliography and Master Index for NetView, NCP, and VTAM 
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Chapter 1. Writing VTAM Exit Routines 


This chapter describes user-coded exit routines that control session management, 
virtual route selection, virtual route pacing window size, trace print utility (TPRINT), 
session accounting, and session authorization processing. 


Session Management Exit Routine 


The session management exit routine enables you to combine session-related func- 
tions (authorization, accounting, gateway path selection, system services control 
point (SSCP) selection, and alias selection) into one exit routine. 


The session management exit routine is called in the SSCPs of the origin logical unit 
(OLU) and destination logical unit (DLU), as well as in every SSCP along the path of 
the SSCP-SSCP session used to support a particular LU-LU session. 


Note: The session management exit routine will not be called in an SSCP used as 
an intermediate routing node (IRN). 


Although the session management exit routine is recommended especially for 
cross-network sessions, it is also recommended for single-network sessions. In the 
latter case, it can replace the authorization and accounting exit routines. It can also 
be called for the adjacent SSCP function and as a directory service for the alias 
selection function. It is not called for gateway path selection for single-network ses- 
sions, since there are no gateway paths to be selected. 


When you use the session management exit routine for gateway path selection in 
cross-network sessions, you can modify the list of alternate gateway paths. The exit 
routine is called with the list of alternate gateway paths and the names and network 
identifiers of the LU-LU session partners. You can modify the order of the list or 
shorten it, thus changing the order in which the gateway paths are considered for 
use in this session. The first entry in the list is the GWPATH for the gateway NCP 
that was used for the SSCP-SSCP session, over which the LU session request was 
received. The gateway path selection function lets you distribute the LU-LU ses- 
sions across gateway NCPs according to your particular requirements. 


Similarly, when you use the session management exit routine for adjacent SSCP 
selection, you can shorten or reorder the list from which the next SSCP used in the 
session setup is chosen. The session management exit routine receives as input 
either a default list or a list of adjacent SSCPs that was built during the previous 
LU-LU session setup for the resource. 


Mvs vm The alias selection function of the session management exit routine is an 
alternative method of translating names that can complement or replace the 
NetView alias application. The alias selection function translates LU names, class- 
of-service (COS) names, and logmode names. It can also determine owning SSCP 
names. After processing the names passed to the exit, you can indicate that the 
NetView alias application should be called to translate any names not already trans- 


* 
Trademark of the IBM Corporation. See “Special Notices” on page iii for a list of all IBM trademarks used in this book. 
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Session Management Exit Routine 


lated, the NetView alias application should not be called at all, or the session should 


be terminated. 


Examples of when the session management exit routine functions are driven are 
shown in Table 2. A sample cross-network session between APPLA and APPLB, 
illustrating when the functions are driven, is shown in Figure 10n page 5. A 
sample cross-network session for INIT OTHER CD processing is illustrated in 

Figure 2 on page 6. These sample sessions do not include the alias selection func- 
tion. Examples of session flows for the alias selection function are shown in “mvs 
vm Session Flow for Alias Selection Function” on page 39. 


Table 2. Example of Session Management Exit Routine Functions 


Function 
Begin 
Adjacent SSCP selection 


Gateway path selection 


Alias selection 
MVS VM 


Initial authorization 


First time 


Second through nth time 


Secondary authorization 


Initial accounting 


Final accounting 


End 


4 VTAM Customization 


Driven 
Once during VTAM initialization. 


Once during session initialization when the adjacent 
SSCP table is being built. 


During session initialization each time a new adjacent 
SSCP is selected and gateway path list is built (cross- 
network only). 


During session initialization each time a name needs 
to be translated and the NetView alias application 
might be called. 


Once during session initialization. 


After an adjacent SSCP is selected in the DLU direc- 
tion. (For INIT OTHER CD, this occurs after the SSCP 
is selected in the secondary logical unit (SLU) direc- 
tion.) 


Each time a new adjacent SSCP is selected in the DLU 
direction. 


Once during session initialization when the ODLU has 
been located and more information is known. 


Once during session initialization when all session 
started signals have arrived and the session is active. 


Once during session termination. 


Once during VTAM termination. 


LY43-0046-01 © Copyright IBM Corp. 1984, 1990 


“Restricted Materials of IBM” Session Management Exit Routine 
Licensed Materials — Property of i8M 


SESSION INITIALIZATION 
NETA SHR. = SHR NETB 


APPLA APPLB 


(1) Adjacent SSCP selection 
(2) Gateway path selection! 
(3) Initial authorization 


CDINIT 


(4) Gateway path selection! 
(5) Adjacent SSCP selection 


s RNAA 

IrIy7C0oe s=eeeS0q0y50quQ0QQ—V—_—V—V_—_—_ 

.RNAA response 

LK 
(6) Initial authorization 
(7) Secondary authorization 


SETCV 


.«.e..9....0—0  —:.:.:._—.0.0.0.. 
~SETCV response 
SSeS... ee 
; CDINIT response 
er ES 
(8) Secondary authorization 


. COCINIT 
ee SEY 


SETCV : 


—_—_—_—_—_—_—_—_—— | 
SETCV response. 
ess. SSS. 


COCINIT response ‘ 
a 


e 


COSESST 
CDOSESST response 
(9) Initial accounting (9) Initial accounting 
SESSION TERMINATION 
NETA . NETB 


* 


APPLA APPLB 


CDSESSEND 


CDSESSEND response 


(10) Final accounting . (16) Final accounting 


Figure 1. Sample Cross-Network Session 


1 This function applies to MVS and VM only (see figures 1 and 2). 
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(8) Secondary authorization ‘ 

INIT OTHER CD response : 


COCINIT 


]____—_—wewe 


SETCV response. 
COCINIT response . 


—_—_—_e_e_—,_, 


CDSESST ‘ 
. COSESST response 
(9) Initial accounting (9) Initial accounting 


SESSION TERMINATION 
NETA SHR . SHR NETB 


APPLA1 APPLA2 APPLB 


COSESSEND 


CDSESSEND response 


(16) Final accounting ; (10) Final accounting 


Figure 2. Sample Cross-Network Session for Init Other CD 
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The following sections contain information you need to write this routine. 


Register Contents 


When VTAM passes control to the session management exit routine, register con- 
tents are as follows: 


Register 1: Address of a variable-length list of virtual storage addresses, 
which point to fields of parameter data. The end of the parameter 
list is indicated by a “1” in the high order bit of the last word. 


Register 13: Address of an 18-fullword save area. 
Register 14: Return address. 
Register 15: Address of the entry point of the routine. 


The final register contents vary depending on which function is being performed. 
They are described in the sections pertaining to the individual functions. 


If any function other than the end function abends, VTAM posts return code 16 and 
sends a message to the operator. When the session management exit routine is 
disabled: 


¢ \VTAM authorizes all sessions and discards accounting data meant for the exit 
routine 


¢ GWPATH definition statement determines the gateway path selection 


e VTAM selects an adjacent SSCP from the original list and invokes the NetView 
alias application, if active. 


Several functions are defined for the session management exit routine. All func- 
tions except the begin function are optional. 


The parameters VTAM passes to the exit routine are described in the following 
section. Although the parameter lists vary depending on the use of the exit routine, 
the basic format is the same for all of the functions for which the exit routine is 
called. The input for each function appears at the same location in each parameter 
list. 


The possible input parameter lists are: 


e Begin 

¢ Initial authorization 

¢ Secondary authorization 

e Initial accounting 

¢ Final accounting 

¢ mvs Session takeover accounting (XRF only) 
¢ mvs vm Gateway path selection 

e Adjacent SSCP selection 

¢ mvs vm Alias selection 

e End. 


Table 3 on page 8 and Table 40n page 9 summarize the parameters contained in 
each list. 


The function code (described in “Function Code and Related Session Information” 
on page 20) indicates the function being processed. 
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If you do not provide a session management exit routine, a session accounting exit 
routine, or a session authorization exit routine, VTAM authorizes all sessions and 
discards accounting data meant for the exit routine. mvs vm When you provide none 
of these exit routines, VTAM: 


¢ Selects a gateway path from the list determined by the GWPATH definition state- 
ments 


¢ Selects an adjacent SSCP from the default list 


e Sends all requests to a NetView alias application, if one is active. 


Parameter List Structure 


Table 3. Summary of Parameter Lists for Session Management Exit Routine (Part 1) 


INITIAL SECONDARY INITIAL FINAL 
FUNCTION BEGIN AUTHORIZATION AUTHORIZATION ACCOUNTING ACCOUNTING 
Ofiset Function Function Function Function Function 
Code Code Code Code Code 
dec hex X'FE' x‘'00' x'ot1' X'02' X'03' 
0 0 Environment Environment Environment Environment Environment 
Vectors Address Vectors Address Vectors Address Vectors Address Vectors Address 
See Table 14 See Table 14 See Table 14 See Table 14 See Table 14 
4 4 Function Code and Function Code and Function Code and Function Code and Function Code and 
Related Session Related Session Related Session Related Session Related Session 
Information Address Information Address Information Address information Address Information Address 
See Table 15 See Table 15 See Table 15 See Table 15 See Table 15 
8 8 User Data Field User Data Field User Data Field User Data Field User Data Field 
Address Address Address Address Address 
12 Cc Exit Options PLU Resource ID PLU Resource ID PLU Resource ID PLU Resource ID 
Address See Table 16 Control Vector Address Control Vector Address Control Vector Address Control Vector Address 
See Table 17 See Table 17 See Table 17 See Table 17 
16 10 N/A SLU Resource ID SLU Resource ID SLU Resource ID SLU Resource ID 
Control Vector Address Contro! Vector Address Control Vector Address Control Vector Address 
See Table 17 See Table 17 See Table 17 See Table 17 
20 14 N/A Session ID Address Session ID Address Session ID Address Session ID Address 
24 18 N/A Reserved Reserved Time of Day Address Time of Day Address 
28 1c N/A OLU Gateway OLU Gateway OLU Gateway OLU Gateway 
Information Vector Information Vector Information Vector Information Vector 
Address See Table 19 Address See Table 19 Address See Table 19 Address See Table 19 
32 20 N/A Reserved DLU Gateway OLU Gateway OLU Gateway 
Information Vector Information Vector Information Vector 
Address See Table 22 Address See Table 22 Address See Table 22 
36 24 N/A OLU Adjacent SSCP OLU Adjacent SSCP OLU Adjacent SSCP OLU Adjacent SSCP 
Vector Address Vector Address Vector Address Vector Address 
See Table 23 See Table 23 See Table 23 See Table 23 
40 28 N/A For INIT OTHER CD, DLU Adjacent SSCP OLU Adjacent SSCP DOLU Adjacent SSCP 
DLU Adjacent SSCP Vector Address Vector Address Vector Address 
Vector Address See Table 24 See Table 24 See Table 24 
See Table 24 
44 2C N/A N/A N/A N/A N/A 
48 30 N/A N/A N/A N/A N/A 
Reg.15 
Return 
Code 0 0,4,8,12 0.8 0 0 
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Table 4. Summary of Parameter Lists for Session Management Exit Routine (Part 2) 


MVS VM MVS SESSION ADJACENT MVS VM 
GATEWAY PATH TAKEOVER SSCP ALIAS 
FUNCTION SELECTION ACCOUNTING SELECTION SELECTION END 
Oftset Function Function Function Function Function 
Code Code Code Code Code 
dec hex x'04' x'05' X'06' X'07' X'FF' 
0 0 Environment Environment Environment Environment Environment 
Vectors Address Vectors Address Vectors Address Vectors Address Vectors Address 
See Table 14 See Table 14 See Table 14 See Table 14 See Table 14 
4 4 Function Code and Function Code and Function Code and Function Code and Function Code and 
Related Session Related Session Related Session Related Session Related Session 
Information Address information Address Information Address Information Address Information Address 
See Table 15 See Table 15 See Table 15 See Table 15 See Table 15 
8 8 User Data Field User Data Field User Data Field User Data Field User Data Field 
Address Address Address Address Address 
12 C PLU Resource ID PLU Resource ID PLU Resource ID PLU Resource ID NIA 
Control Vector Address Control Vector Address Control Vector Address Control Vector Address 
See Table 17 See Table 17 See Table 17 See Table 17 
16 10 SLU Resource ID SLU Resource ID SLU Resource ID SLU Resource ID N/A 
Control Vector Address Control Vector Address Control Vector Address Control Vector Address 
See Table 17 See Table 17 See Table 17 See Table 17 
20 14 Session (D Address Session ID Address Session ID Address Session ID Address N/A 
24 18 Reserved Time of Day Address Reserved Reserved N/A 
28 1c Gateway Path OLU Gateway SSCP Name List OLU Gateway N/A 
Selection List Information Vector Address See Table 21 Information Vector 
Address See Table 20 Address See Table 19 Address See Table 19 
32 20 N/A DLU Gateway N/A DLU Gateway N/A 
Information Vector Information Vector 
Address See Table 22 Address See Table 22 
36 24 N/A OLU Adjacent SSCP N/A OLU Adjacent SSCP N/A 
Vector Address Vector Address 
See Table 23 See Table 23 
40 28 N/A OLU Adjacent SSCP N/A DLU Adjacent SSCP N/A 
Vector Address Vector Address 
See Table 24 See Table 24 
44 2C N/A N/A N/A Alias Selection N/A 


Input Parameter 
List Address 
See Table 25 


48 30 N/A N/A N/A Alias Selection N/A 
Output Parameter 
List Address Table 27 


Reg.15 
Return 
Code 0,4 0 0.4 0,4,8,12,16,20 0 


Begin Function (Function Code X'FE') 
The begin function of the session management exit routine is required; all other 
functions are optional. This function is processed only once during VTAM initializa- 
tion, before any of the other functions are processed. 


During begin function processing, the exit routine selects the other functions to 
process for all LU-LU sessions. If not selected at this time, the session management 
exit routine is not invoked for the other functions. Table 5 on page 10 shows the 
begin parameter list pointed to by register 1. The parameters are described in 
“Parameter Descriptions” on page 19. 


LY43-0046-01 © Copyright IBM Corp. 1984, 1990 Chapter 1. Writing VTAM Exit Routines 9 


Session Management Exit Routine “Restricted Materials of IBM” 
Licensed Materials — Property of IBM 


Table 5. Begin-Function Parameter List 


Dec (Hex) Size 
Offset (Bytes) Description 
0 (0) 4 Address of environment vectors 
4 (4) 4 Address of function code and related session information 
8 (8) 4 Address of user data field 
12 (C) 4 Address of exit options 


Final Register Contents: The routine must leave the register status as follows: 


Registers 1— 14: Restore these registers. 
Register 15: 0. 


If the exit routine returns an invalid return code (that is, a nonzero return code) or 
invalid data as a result of processing the begin function, VTAM continues as if no 
exit routine exists. All sessions are authorized, accounting data is discarded, the 
list of gateway paths determined by the GWPATH statements are used for gateway 
path selection, an adjacent SSCP is selected from the original list, and the NetView 
alias application is used for translation if the application is active. VTAM issues 
message !IST793E to inform the operator. 


If the alias selection function is chosen during begin processing, the alias parameter 
list is obtained at this time. If the parameter list cannot be obtained, VTAM issues 
IST793E and the alias selection function is not invoked to perform translations. 


Initial Authorization Function (Function Code X'‘00°') 
The session management exit routine invokes this function during session initiation 
as well as during SSCP takeover. Using this function, the session management exit 
routine may or may not allow a session. If, during the begin function, VTAM sets the 
proper bit in the exit options, indicating that authorization is allowed for INIT OTHER 
CD processing as well as normal initiation processing, the initial authorization func- 
tion is also invoked for CLSDST PASS processing. The exit routine also invokes 
both initial and secondary authorization exits during LU takeover processing if the 
sessions being taken over were established using extended BIND protocols. 


For normal initiate processing, the initial authorization function may also defer the 
decision of allowing a session to the secondary authorization function when more 
information is available, for example: 


e The DLU’s real name 
¢ The DLU’s network identifier 
¢ The DLU’s owning SSCP. 


For normal! initiate processing, the initial authorization function does not know the 
DLU gateway information vector (GIV) during initial authorization time. It can, 
however, be determined by looking at the parameter list obtained when the sec- 
ondary authorization is invoked. 


if the initial authorization function is not selected during begin function processing, 
VTAM defers authorization to the secondary authorization function. If the exit 
routine does not process secondary authorization either, VTAM automatically 
authorizes the session. 
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CLSDST PASS (INIT OTHER CD) processing is slightly different for initial authori- 
zation. The secondary authorization function is not driven for CLSDST PASS proc- 
essing when neither the primary logical unit (PLU) nor the SLU are in the initiating 
LU’s host; therefore, session authorization cannot be deferred. Furthermore, infor- 
mation is available through both the OLU and the DLU gateway information vectors 
for this processing. (The vectors contain information about the initiating logical unit 
(ILU) and SLU rather than the OLU and DLU.) 


Table 6 shows the initial-authorization function parameter list pointed to by register 
1. The parameters are described in “Parameter Descriptions” on page 19. 


Table 6. Initial-Authorization-Function Parameter List 


Dec (Hex) Size 
Offset (Bytes) Description 
0 (0) 4 Address of environment vectors 
4 (4) 4 Address of function code and related session information 
8 (8) 4 Address of user data field 
12 (C) 4 Address of PLU resource identifier contro! vector 
16 (10) 4 Address of SLU resource identifier control vector 
20 (14) 4 Address of session ID 
24 (18) 4 Reserved 
28 (1C) 4 Address of OLU gateway information vector 
32 (20) 4 Reserved 
36 (24) 4 Address of OLU adjacent SSCP vector. (For INIT OTHER 
CD, address of the ILU adjacent SSCP vector) 
40 (28) 4 Address of SLU adjacent SSCP vector. (Present only for 


INIT OTHER CD) 


Final Register Contents: The routine must leave the register status as follows: 
Registers 1— 14: Restore these registers. 


Register 15: 0, session setup authorized; do not schedule the secondary 
authorization function. 


4, session setup authorized; secondary authorization is 
required if an INIT OTHER CD request is not being processed. 
This return code is valid only if the exit routine processes the 
secondary authorization function. Otherwise, session setup is 
not authorized, and the session setup fails. For INIT OTHER 
CD processing, this return code is equivalent to a zero return 
code. 


8, session setup not authorized and session setup fails. Do not 
reroute. 


12, session setup not authorized. Allow sending SSCP to 
reroute. 


Note: If this return code is set in the host of the origin LU or if 
this return code is set during INIT OTHER CD processing, it is 
handied as return code 8. 
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Note: An invalid return code (that is, a return code not defined above) always 
means that session setup is not authorized and the session setup fails. VTAM 
issues message IST793E to inform the operator. 


Secondary Authorization Function (Function Code X'01') 
The secondary authorization function may receive authorization requests that were 
deferred by the initial authorization function or all session authorization requests, if 
the exit routine does not process the initial authorization function. This function is 
processed for initiation or LU takeover if the sessions being taken over were estab- 
lished using extended BIND protocols. A bit setting in the related session informa- 
tion indicates whether the invocation is because of session setup or failure. The 
secondary authorization function may receive more information about a session 
from VTAM than does the initial authorization function. That is, if the DLU’s real 
name, network identifier, and owning SSCP were not known at initial authorization, 
they are known at secondary authorization since the DLU gateway information 
vector is provided. 


if the exit routine processes neither initial nor secondary authorization functions 


(because they were not selected during begin function processing), all sessions are 
authorized. 


Table 7 shows the secondary authorization function parameter list pointed to by 
register 1. The parameters are described in “Parameter Descriptions” on page 19. 


Table 7. Secondary-Authorization-Function Parameter List 


Dec (Hex) Size 

Offset (Bytes) Description 

0 (0) 4 Address of environment vectors 

4 (4) 4 Address of exit routine function code 

8 (8) 4 Address of user data field 

12 (C) 4 Address of PLU resource identifier contro! vector 
16 (10) 4 Address of SLU resource identifier control vector 
20 (14) 4 Address of session ID 

24 (18) 4 Reserved 

28 (1C) 4 Address of OLU gateway information vector 

32 (20) 4 Address of DLU gateway information vector 

36 (24) 4 Address of OLU adjacent SSCP vector 

40 (28) 4 Address of DLU adjacent SSCP vector 


This function is processed when the CDINIT response is received. 


Final Register Contents: The routine must leave the register status as follows: 


Registers 0— 14: Restore these registers. 
Register 15: 0, session authorized. 
8, session setup not authorized, and session setup fails. 


Note: An invalid return code always means that session setup is not authorized and 
the session setup has failed. VTAM issues message IST793E to inform the operator. 
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Initial and Final Accounting Functions (Function Codes X‘'02' and X'03') 
The initial accounting function is processed at session initiation time. The final 
accounting function is processed at session termination time. These functions pass 
accounting information only. No results are returned to VTAM. 


lf the initial accounting function is selected for processing, the final accounting func- 
tion is also selected for processing. 


If the session management exit routine does not process the accounting functions 
(because they were not selected during begin function processing), VTAM discards 
data meant for the exit routine. 


Table 8 shows the accounting-function parameter list (for both initial and final 
accounting function) pointed to by register 1. The parameters are described in 
“Parameter Descriptions” on page 19. 


Table 8. Accounting-Function Parameter List 


Dec (Hex) Size 
Offset (Bytes) Description 
0 (0) 4 Address of environment vectors 
4 (4) 4 Address of exit routine function code 
8 (8) 4 Address of user data field 
12 (C) 4 Address of PLU resource identifier control vector 
16 (10) 4 Address of SLU resource identifier control vector 
20 (14) 4 Address of session ID 
24 (18) 4 Address of time of day field 
28 (1C) 4 Address of OLU gateway information vector 
32 (20) 4 Address of DLU gateway information vector 
36 (24) 4 Address of OLU adjacent SSCP vector 
40 (28) 4 Address of DLU adjacent SSCP vector 


Final Register Contents: The routine must leave the register status as follows: 


Registers 0— 14: Restore these registers. 
Register 15: 0. 


Note: An invalid return code (that is, a nonzero return code) is ignored. VTAM 
issues message IST793E to inform the operator. 


mvs vm Gateway Path Selection Function (Function Code X'04') 
The gateway path selection function enables you to shorten or reorder the list of 
gateway paths determined by the GWPATH definition statements. (See VTAM 
Resource Definition Reference for an explanation of the GWPATH statement.) If this 
function is not selected during begin function processing, VTAM uses the original 
gateway path list determined by the GWPATH statements. 


Table 9 on page 14 shows the gateway path selection function parameter list 
pointed to by register 1. The parameters are described in “Parameter 
Descriptions” on page 19. 
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Table 9. Gateway-Path-Selection-Function Parameter List 


Dec (Hex) Size 
Offset (Bytes) Description 
0 (0) 4 Address of environment vectors 
4 (4) 4 Address of exit routine function code 
8 (8) 4 Address of user data field 
12 (C) 4 Address of PLU resource identifier control vector 
16 (10) 4 Address of SLU resource identifier contro! vector 
20 (14) 4 Address of session |ID 
24 (18) 4 Reserved 
28 (1C) 4 Address of gateway path selection list 


Final Register Contents: The routine must leave the register status as follows: 


Registers 0— 14: Restore these registers. 


Register 15: 0, proceed with session setup; the gateway path list returned 
by the exit routine is used. Modification of the gateway path 
list by the exit routine is optional. 


4, proceed with session setup; the original gateway path list 
(determined by the GWPATH definition statements) is used. 


Note: If an invalid return code is received, the original gateway path list deter- 
mined by the GWPATH statements is used for gateway path selection. The original 
gateway path list is also used if the returned list is empty or if it is larger than the 


list that was passed to the routine. VTAM issues message IST793E to inform the 
operator. 


mvs Session Takeover Accounting Function for XRF (Function Code X'05') 
This primary function code indicates that the session management exit routine has 
been called to process a session takeover by the alternate XRF application. The 
exit routine is driven for this function when the alternate application has completed 
its takeover of a session. The session takeover accounting function notifies the exit 
routine of a change of session status. 


If this function is not selected during begin function processing, data intended for it 
is discarded. 


A bit setting in the related session information (shown in Table 15 on page 21) indi- 
cates whether a session is a backup XRF session. This setting applies to primary 
function codes hex 00—07. It does not apply to the begin and end functions. 
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Table 10 shows the session takeover accounting function parameter list that is 
pointed to by register 1. These parameters are described in “Parameter 
Descriptions” on page 19. 


Table 10. Session-Takeover-Accounting-Function Parameter List 


Dec (Hex) Size 

Offset (Bytes) Description 

0 (0) 4 Address of environment vectors 

4 (4) 4 Address of function code and related:session information 
8 (8) 4 Address of user data field 

12 (C) 4 Address of PLU resource identifier contro! vector 
16 (10) 4 Address of SLU resource identifier control vector 
20 (14) 4 Address of session ID 

24 (18) 4 Address of time of day 

28 (1C) 4 Address of OLU gateway information vector 

32 (20) 4 Address of DLU gateway information vector 

36 (24) 4 Address of OLU adjacent SSCP vector 

40 (28) 4 Address of DLU adjacent SSCP vector 


Final Register Contents: The routine must leave the register status as follows: 


Registers 0— 14: Restore these registers. 
Register 15: 0. 


Note: An invalid return code (that is, a nonzero return code) in register 15 is 
ignored. VTAM issues message !IST793E to inform the operator. 


Adjacent SSCP Selection Function (Function Code X'06') 
An SSCP invokes the adjacent SSCP selection function during the processing of an 
LU-LU session request to select the SSCP to which the request is routed. This func- 
tion enables you to shorten or reorder the list of SSCPs from which the next SSCP 
used in session setup is chosen during CDINIT or DSRLST routing. This function is 
invoked for direct search list (DSRLST) routing only if it is enabled during the begin 
function. If no adjacent SSCPs exist, this function is not invoked. 


The session management exit routine receives as input the user-defined list of adja- 
cent SSCPs and the list of adjacent SSCPs that were built during the previous LU-LU 
session setup for the same resource (if any). 


By using the dynamic adjacent SSCP table function in conjunction with the adjacent 
SSCP selection function, you can maintain control of session routing without having 
to define adjacent SSCP tables. The SSCP selection function is provided with a list 
of all active adjacent SSCPs, which it alters as necessary, to control session routing. 
To use the dynamic adjacent SSCP table function, you must specify the function in 
the start options. 
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Both the user-defined tables and the dynamic tables are searched in the following 
manner: 


1. If the NETID and the CDRM names are known, a search is done for a table coin- 
ciding with the known information. 


2. If that table is not found or if only NETID is known, a search is done for a table 
defined with just the NETID given. 


3. If an attempt to find that table fails or if only the CDRM name is known, the indi- 
cated CDRM adjacent SSCP table for all networks is searched. 


4. {f an attempt to find that table fails, the default adjacent SSCP table for all! net- 
works is used. 


5. If an attempt to find that table fails and the SSCP is using the dynamic adjacent 
SSCP function, the dynamic adjacent SSCP table is used. 


6. If no tables exist or if a usable table could not be located, routing is attempted to 
any dynamic adjacent SSCP entries. This includes entries from the 
CDRM-CDRM sessions for this host. 


Note: If the owner is known, it is provided in the PLU or the SLU resource iden- 
tification vector, or both. 


Table 11 shows the SSCP-selection-function parameter list pointed to by register 1. 
The parameters are described in “Parameter Descriptions” on page 19. 


Table 11. SSCP-Selection-Function Parameter List 


Dec (Hex) Size 
Offset (Bytes) Description 
0 (0) 4 Address of environment vectors 
4 (4) 4 Address of exit routine function code 
8 (8) 4 Address of user data field 
12 (C) 4 Address of PLU resource identifier contro! vector 
16 (10) 4 Address of SLU resource identifier control vector 
20 (14) 4 Address of session ID 
24 (18) 4 Reserved 
28 (1C) 4 Address of SSCP name list 


Final Register Contents: The routine must leave the register status as follows: 
Registers 0— 14: Restore these registers. 


Register 15: 0, proceed with session setup; use SSCP name list returned by 
this function. Changing the SSCP name list is optional. 


4, proceed with session setup; standard VTAM routing is used. 


If an invalid return code is returned or if the exit routine terminates abnormally, the 
session initiation request continues to be processed using the original list of adja- 
cent SSCPs received by the exit routine. VTAM also uses the original adjacent 
SSCP list if the returned list is invalid, for instance, if it is empty or if it is larger than 
the fist that was passed to the routine. VTAM issues error message IST793E to 
inform the operator. 
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Mvs VM Alias Selection Function (Function Code X'07') 


This function is processed along the session setup path during session initiation. 
The alias selection function can be called during: 


e INIT OTHER CD processing to translate the PLU and the SLU names, SLU 
logmode name, PLU- and SLU-owning SSCP names, and SLU COS name 


e CDINIT request routing processing to determine the DLU-owning SSCP name 
and to translate the DLU real names, OLU alias name, DLU logmode and COS 
names, and associated LU alias names 


¢ CDINIT response time to translate the COS names, associated LU alias names, 
and USERVAR names 


e DSRLST routing time to translate the DLU real names and the USERVAR names 
and to determine the DLU-owning SSCP names. 


Table 12 shows the alias-selection-function parameter list pointed to by register 1. 
The parameters are described in “Parameter Descriptions” on page 19. 


Table 12. Alias-Selection-Function Parameter List 


Dec (Hex) Size 

Offset (Bytes) Description 

0 (0) 4 Address of environment vectors 

4 (4) 4 Address of exit routine function code 

8 (8) 4 Address of user data field 

12 (C) 4 Address of PLU resource identifier control vector 
16 (10) 4 Address of SLU resource identifier control vector 
20 (14) 4 Address of session ID 

24 (18) 4 Reserved 

28 (1C) 4 Address of OLU gateway information vector 

32 (20) 4 Address of DLU gateway information vector 

36 (24) 4 Address of OLU-adjacent SSCP vector 

40 (28) 4 Address of DLU-adjacent SSCP vector 

44 (2C) 4 Address of alias input parameter list 

48 (30) 4 Address of alias output parameter list 
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Final Register Contents: The routine must leave the register status as follows: 
Registers 1— 14: Restore these registers. 


Register 15: 0, no information has been translated; do not invoke the 
NetView alias application. 


4, no information has been translated; invoke the NetView alias 
application to translate all data. 


8, some information has been translated; do not invoke the 
NetView alias application. 


12, some information has been translated; invoke the NetView 
alias application to translate the remaining information. 


16, session initiation cannot continue through this SSCP; allow 
the sending SSCP to reroute the request. 


20, session initiation cannot continue through this SSCP; do not 
allow the sending SSCP to reroute the request. The session 
will fail to set up. 


Note: Only CDINIT and DSRLST requests can be rerouted. All 
other RU types fail. 


End Function (Function Code X'FF') 
This function of the session management exit routine is processed during VTAM ter- 
mination (HALT or HALT QUICK). This function should perform any cleanup 
required and return processing to VTAM. Note that HALT CANCEL causes VTAM to 
abend. In this case, the end function is not processed. 


Table 13 shows the end-function parameter list pointed to by register 1. The param- 
eters are described in “Parameter Descriptions” on page 19. 


Table 13. End-Function Parameter List 


Size 
Offset (Bytes) Description 
0 4 Address of environment vectors 
4 4 Address of exit routine function code 
8 4 Address of user data field 


Final Register Contents: The routine must leave the register status as follows: 


Registers 0— 14: Restore these registers. 
Register 15: 0, continue with termination. 


Note: An invalid return code (that is, a nonzero return code) causes VTAM to con-. 
tinue termination. VTAM issues message IST793E to inform the operator. 
VTAM termination does not complete if the exit routine does not complete. In this 


case, the operator must issue one of the following to terminate VTAM: 


¢ MVS VM aHALT CANCEL command 
* vse a CANCEL Fx (the VTAM partition). 
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Parameter Descriptions 


The descriptions of each of the parameters that follow refer to Table 5 on page 10 
through Table 13 on page 18. These figures are summarized in Table 3 on page 8. 


Environment Vector List 
The address of the environment vector list is the first word of the parameter list for 
all function codes. These vectors, which are preceded by a 2-byte length field, make 
it possibie for your installation to use a single exit routine, installed in each host, to 
collect session authorization and accounting data. Aithough‘all information col- 
lected may be combined for analysis, it is possible to identify the host at which the 
_ data was collected. 


The environment vector list has the same format as the resource identification 
vector list described in VTAM Programming. (Do not confuse this with the resource 
identifier control vector described later in this section.) The parameter list points to 
the environment vector list in Table 14. 


Table 14 (Page 1 of 2). Environment Vectors 


Size 
Comments Offset (Bytes) Description 
A header precedes the list of vectors: 
0 2 Total length of the parameter list 


including this length field (m) 


This header is followed by several vectors, which may be in any order. The network iden- 
tification vector: 


0 1 Length of the vector including this field 
(n) 

1 1 iD of the vector (X'06') 

2 n—2 ID of the network in which this exit 
routine is operating (from the NETID 
start option) 

The SSCP-name vector: 

0 1 Length of the vector including this field 
(n) 

1 1 ID of the vector (X'07') 

2 n—2 SSCP name of the host in which this exit 


is operating. The start option 
SSCPNAME is required. 


The host-PU-name vector: 


0 1 Length of the vector including this field 
(n) 

1 1 ID of the vector (X'08') 

2 n—2 Name of the host in which this exit is 
operating (from the HOSTPU start 
option) 


The host-PU-network-address vector: 
0 1 Length of the vector including this field 
1 1 ID of the vector (X'09') 
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Table 14 (Page 2 of 2). Environment Vectors 


Size 
Comments Offset (Bytes) Description 
2 6 Network address of the host PU 


The adjacent OLU-network-name vector is used for the following functions: 


Initia! authori- 0 1 Length of the vector including this field 
zation 

Secondary authori- 

zation If this information is not applicable, the 
Initial accounting length field is represented by X‘'00' and 
Final accounting the actual length of the vector is X'01'. 
Gateway path 

selection 

Adjacent SSCP 

selection 

Alias selection 


1 1 ID of the vector (X'0A') 


2 n—2 Network name of the adjacent network 
in the OLU direction 


The adjacent DLU-network-name vector is used for the following functions: 


Secondary authori- 0 1 Length of the vector including this field 
zation 
initial accounting 
Final accounting This field is zero if this information is 
Alias selection not applicable. 

1 1 ID of the vector (X‘'0B') 

2 n—2 Network name of the adjacent network 


in the DLU direction 


Function Code and Related Session Information 
The address of the function code and the related session information is always 
passed to the session management exit routine as the second parameter in the 
function parameter list. The function code indicates which of the functions of the 
session management exit routine will be processed. The first byte (byte 0) is the 
function code. The parameters passed to the exit routine depend on the function 
code. | 


The second and third bytes (bytes 1 and 2, respectively) are the related session 
information. The second byte contains information about the initiator of the session, 
which type of request (CDINIT or DSRLST) is being processed, whether the session 
management exit routine is being driven for takeover, and whether a session is a 
backup extended recovery facility (XRF) session. 


The third byte contains information about the SSCP that invoked the session man- 
agement exit routine and indicates whether the RU was a request or a response, 
and whether an INIT OTHER CD or some other RU was being processed. (The other 
RUs would be CDINIT or DSRLST. You can determine the RU by referring to the 
related session information field.) 
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See Table 15 for function code and related session information. 


Table 15 (Page 1 of 3). Function Code and Related Session Information 
Byte Description 
0 Function Code: 


X'00' The exit routine has been called for initial session authori- 
zation; only partial information may be available. This function 
is processed for initiation or LU takeover if the sessions being 
taken over were established using extended BIND protocols. 


X'01' The exit routine has been called for secondary session authori- 
zation; complete session initiation information is available. 
This function is processed for initiation or LU takeover if the 
sessions being taken over were established using extended 
BIND protocols. A bit setting in the related session information 
indicates whether the invocation is due to session setup or 
failure. 


X'02' The exit routine has been called for session accounting at 
session setup completion. The session is in an active state. 


X'03' The exit routine has been called for session accounting at the 
completion of session termination. 


X'04' The exit routine has been called for gateway path selection. 
The related session information defines whether the function is 
invoked for the DLU or OLU direction. 


X'05' The exit routine has been called for XRF session switch proc- 
essing. 


X'06' The exit routine has been called for SSCP selection. 


X'07' The exit routine has been called for the alias selection function. 
CDINIT, DSRLST, or INIT OTHER CD is being processed by this 
SSCP. 


X'FE' The exit routine has been called to select the functions it will 
process; this begin function is processed only once. 


X'FF' The exit routine has been called to perform required cleanup 
during VTAM termination. This end function is processed only 
once during VTAM termination. 


1 Related Session Information 


The following bit settings indicate whether a session is a backup XRF session. 
(The settings are defined for primary function codes hex 00—07.) 


B'Oj0i “aeuse The session is not a backup XRF session. If the primary 
function code is hex 05, the session is now a primary 
session and was previously a backup session. For all 
other valid primary function codes, the session is either a 
primary session or not enabled for XRF. 


Or leak. eee” The session is a backup XRF session. If the primary 
function code is hex 05, the session was previously a 
primary XRF session. 
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Table 15 (Page 2 of 3). Function Code and Related Session Information 


Byte 


22 VTAM Customization 


Description 


For the session authorization or alias selection functions (primary function 
codes hex 00, 01, or 07), the following flags define the session initiator: 


B'..00 ....' Autologon session (VARY LOGON, LOGAPPL) 

B asl. -ees? PLU requested the session (SIMLOGON, OPNDST 
ACQUIRE). (PLU is the OLU, SLU is the DLU.) 

BY eNO. aaa SLU requested the session (USS logon, INIT SELF). (SLU 
is the OLU, PLU is the DLU.) 

BS yekl- saeee Some other LU requested the session: third party initi- 


ation (CLSDST PASS). 


For the session authorization or alias selection functions (primary function 
codes hex 00, 01 or 07), the following flag defines whether the DLU real 
network ID is assumed: 


Bi scae, -Ocae DLU real network ID is not assumed 
Bi ans. “Leaks DLU real network ID is assumed and is being processed. 


For the SSCP selection or alias selection function (primary function codes hex 
06 or hex 07), the following flag defines whether the function is invoked for 
CDINIT or DSRLST routing: 


B iia Ose" SSCP or alias selection invoked for CDINIT routing 
Becks. leu SSCP or alias selection invoked for DSRLST routing. 


For the gateway path selection function (primary function code hex 04), the fol- 
lowing flag defines whether the function is invoked for DLU or OLU direction: 


Btisds. <x” Gateway path selection invoked for OLU direction 
Bescé:. eaae Gateway path selection invoked for DLU direction. 


For primary function codes hex 00—02, the following flag indicates whether 
session management exit routine functions are being driven during takeover: 


B vice. seul” Session management exit function not driven for takeover 


B acy. aed Session management exit function driven for takeover. 
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Table 15 (Page 3 of 3). Function Code and Related Session information 
Byte Description 
2 Related Session Information: 


For the initial authorization function (primary function code hex 00) and the 
alias selection function (primary function code hex 07), the following flag 
defines whether the function is invoked for INIT OTHER CD routing, or for 
some other type of RU. The initial authorization function is invoked only for 
INIT OTHER CD and CDINIT routing. 


Be dcack, sess : Alias selection or initial authorization invoked for INIT 
OTHER CD routing 
BB Os54 eae Alias selection or initial authorization invoked for other 


routing (CDINIT or DSRLST routing, see related 
description under Byte 1 above to determine which type 
of routing). 


For the alias selection function (primary function code hex 07), the following 
flag defines which SSCP requested translation: 


B°.06. ....' The SSCP of the ILU requested translation 

BP Ole ceu% The SSCP of the OLU requested translation 

B10. c2n5' The SSCP of the OLU requested translation 

Bally. cae” An intermediate SSCP (neither the OLU nor the DLU) 


requested translation. 


For the alias selection function (primary function code hex 07), the flag defines 
whether the function is invoked because of a request or response: 


ara ° Sareea ck Alias selection invoked because of a request 
B ehadaieeres Alias selection invoked because of a response. 


For the secondary authorization function (primary function code hex 01), the 
following flag indicates whether session initiation has succeeded: 


SB esee Oo Session setup has succeeded; a positive initiate 
response is being processed. 

B asia bean Session setup has failed; a negative response to session 
initiation or a session setup failure request is being proc- 
essed. 


The remaining bits are reserved. 


User Data Field 
The address of the user data field is always passed to the exit routine as the third 
parameter in the function parameter list. This word points to a 4-byte user data 
field, originally initialized to 0, which the exit routine can use for any purpose (for 
example, to store the address of a dynamically obtained storage area). VITAM saves 
the contents of this user field after every successful invocation of the session man- 
agement exit routine, so that it is available to the exit routine the next time it is 
called. 


Notes: 


1. Do not confuse this field with VTAM’s user data field. This field is used only by 
the session management exit routine. 


2. VTAM returns the address of this field on subsequent calls, not the data itself. 
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The address of the exit options field is passed to the exit routine as the fourth 
parameter of the parameter list only for the begin function. This word points to a 
2-byte field that indicates the functions for which the exit routine will be called. This 
field is modified by the exit routine during begin function processing. The bit defi- 


nitions are described below: 


Table 16 (Page 71 of 2). Session Management Exit Routine Options 


Byte Bit 
0 B'l... 


B'0... 


B’.1.. 


BOs: 63% 
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Description 


The exit routine will process the initial authorization 
function. 


The exit routine will not process the initial authori- 
zation function. (The default is 0.) 


The exit routine will process the secondary authori- 
Zation function. 


The exit routine will not process the secondary authori- 
zation function. (The default is 0.) 


The exit routine will process the initial and final 
accounting functions. 


The exit routine will not process the accounting func- 
tions. (The default is 0.) 


The exit routine will process the gateway path 
selection function. 


The exit routine will not process the gateway path 
selection function. (The default is 0.) 


The exit routine will process the end function. 


The exit routine will not process the end function. (The 
default is 0.) 


The exit routine will process the session takeover 
accounting function. 


The exit routine will not process the session takeover 
accounting function (primary function code hex 05). 
(The default is 0.) 


The exit routine will process the SSCP selection func- 
tion. 


The exit routine wil! not process the SSCP selection 
function. (The default is zero.) 


SSCP selection is allowed for DSRLST. 


SSCP selection is not allowed for DSRLST. (The default 
is 0.) 


Session management exit functions are allowed for 
takeover of LU sessions. 


Session management exit functions are not allowed for 
takeover of LU sessions. (The default is 0.) 


Initial authorization is allowed for INIT OTHER CD. 


initial authorization is not allowed for INIT OTHER CD. 
(The default is 0.) 
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Table 16 (Page 2 of 2). Session Management Exit Routine Options 


Byte Bit Description 
Ochs cewe* The exit routine will process the alias selection func- 
tion. 
B0s.. cae The exit routine will not process the alias selection 


function. (The default is 0.) 


The remaining bits are reserved. 


SLU and PLU Resource Identifier Control Vector 
The address of the PLU or the SLU resource identifier contro! vector is passed to the 
exit routine as the fourth or fifth parameter, respectively, of the function parameter 
list for primary function codes hex 00—07. 


These words point to resource identifier control vectors for the PLU and the SLU in 
the session. If the primary function code is hex 01, 02, 03, or 05, all the information 
described later in this section (that is, the resource identifier contro! vector) is avail- 
able. {f the primary function code is hex 00, 04, 06 or 07, only a portion of the infor- 
mation may be available. The real name of the destination LU and the alias name of 
the origin LU may be unknown as well as the name of the destination LU’s owning 
SSCP. If unknown, its field length is set to zero and the length field of the next 
vector immediately follows. 


The PLU and the SLU hierarchy control vector (Table 18 on page 27) follows the 
PLU resource identifier control (RIC) vector in the function parameter lists. The 
hierarchy control vector is not part of the RIC. 


The format of the PLU resource identifier control vector is the same as for the SLU 
(see Table 17 on page 26). 
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Table 17 (Page 1 of 2). PLU and SLU Resource Identifier Control Vector 


Size 
Comments Offset (Bytes) 
0 1 
1 1 
2 1 
3 1 


This is followed by the SSCP name: 


0 1 
1 m 
This is followed by the network ID: 
0 1 
1 n 


This is followed by the real LU name: 


0 1 

1 p 
This is followed by another network ID: 

0 1 

1 q 
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Description 
Vector key (X'19') 


Vector length (number of bytes of vector, not 
including the vector key and length of this 
length field) 


Note: If any of the name fields do not exist 
(cannot be determined at the time the 
exit is called), the length field will be 
zeros and the length field of the next 
name in the RIC vector immediately 
follows. 


The vector data length may include the 
LU-address vectors when sending data 
for session management exits. 


SSCP rerouting count (number of SSCPs 
remaining in the count for this session setup 
request). This byte is reserved if the function 
code and related session information is X'03'. 


Usage indicators. The flags are defined as 
follows: 


B'l... ....' This name has been translated 

B'Q0... ....' This name has not been trans- 
lated 

B'.i.. ....' The resource is the target 
resource 


Note: The OLU is never the 
target resource. 


B'.0.. ....' The resource is not the target 
resource 


Note: The OLU is always the 
target resource. 


Length of SSCP name (m) 
Symbolic name of SSCP that controls the LU 


Length of network !D (n) 


Network !D of the network containing the LU 


Length of the LU name (p) 


Network name of the LU (real name) 


Length of network ID (q) 


Network ID of the network in which the following 
alias LU is known 


LY43-0046-01 © Copyright IBM Corp. 1984, 19880 


“Restricted Materials of IBM" Session Management Exit Routine 
Licensed Materials — Property of IBM 


Table 17 (Page 2 of 2). PLU and SLU Resource Identifier Control Vector 


Size 
Comments Offset (Bytes) Description 


This is followed by the alias LU name: 
0 1 Length of alias LU name (r) 
1 r Alias LU name 


This is followed by three LU-address vectors. (The LU-address vectors are not part of the 


RIC vector.) 

0 1 ID of the vector (X'1A') 

1 1 Vector length (number of bytes of vector, not 
including the vector key and length of this 
length field) 

2 6 PLU or SLU address in this network 

8 1 This byte is not filled in when passed to the exit. 

9 1 This byte is not filled in when passed to the exit. 

0 1 ID of the vector (X'1A‘) 

1 1 Vector length (number of bytes of vector, not 
including the vector key and length of this 
length field) 

2 6 PLU or SLU address in the adjacent network in 
the OLU direction 

8 1 This byte is not filled in when passed to the exit. 

9 1 This byte is not filled in when passed to the exit. 

0 1 ID of the vector (X‘1A') 

1 1 Vector Jength (number of bytes of vector, not 
including the vector key and length of this 
length field) 

2 6 PLU or SLU address in the adjacent network in 
the DLU direction 

1 This byte is not filled in when passed to the exit. 

9 1 This byte is not filled in when passed to the exit. 


Table 18 (Page 1 of 2). PLU and SLU Hierarchy Control Vector 


Size 
Comments Ottset (Bytes) Description 


The PLU and the SLU resource identifier contro! vectors are each followed by a hierarchy 
resource vector. (The hierarchy vector is not part of the RIC vector.) 


0 1 ID of the vector (X'FF') 

1 1 Vector length (number of bytes of vector, not 
including the vector key and length of this 
length field) 

2 1 Number of hierarchy resource entries (n) 
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Table 18 (Page 2 of 2). PLU and SLU Hierarchy Control Vector 


Size 
Comments Offset (Bytes) Description 


This header is followed by a variable number (n) of hierarchy resource entries. 


0 8 Resource name 
8 1 Resource type 26, add dec 27-29. 
Dec (Hex) 


1(1) Communication controller 
2 (2) APPL major node 
3 (3) Local non-SNA major node 
4(4) Switched major node 
5 (5) Local SNA major node 
6 (6) CDRM major node 
7 (7) CDRSC major node 
8 (8) CA major node 
9(9) Reserved 
10 (A) CDRM 
11(B) Reserved 
12 (C) GROUP 
13 (D) Reserved 
14 (E) LINE 
15 (F) Direct attachment node 
16 (10) APPL 
17 (11) Reserved 
18 (12) PU 
19 (13) Reserved 
20 (14) Reserved 
21 (15) Reserved 
22 (16) LU 
23 (17) Link station 
24 (18) CDRSC 
25 (19) Reserved 
26 (1A) Reserved 
27 (1B) Reserved 
28 (1C) LAN major node 
29 (1D) Packet major node 


Note: If this field indicates the resource is an 
LU and the resource information indicates that 
the resource is not within this network, the 
session is being established using non-native 
connection. 


9 3 Reserved 


Session Identifier 
The session !D is passed to the exit routine for all primary function codes except hex 
FE and FF. 


This word of the parameter list points to an 8-byte session identifier. It is a unique 


identifier for this session within the SSCP in which the session management exit 
routine is scheduled. 
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Time-of-Day Field 
This word of the parameter list points to an 8-byte field containing the time of day 
that the session was started (for primary function code hex 02), ended (for primary 
function code hex 03), or taken over (for primary function code hex 05). 


The time-of-day field is in system format time. 


mvs VM OLU Gateway Information Vector 
This word of the parameter list points to the OLU gateway information vector. 


This word is nonzero only if there is an SSCP in the OLU direction that is a gateway 
SSCP and the session is cross-network. If the exit routine is called within the 


network of the origin LU, there is no such gateway NCP and the field is set to zero. 


The OLU gateway information vector provides the gateway NCP name and COS 
names for the gateway in the direction of the origin LU. 


The format of the OLU gateway information vector is shown in Table 19. Its format 
is the same as that of the DLU gateway information vector. 


Table 19. Format of OLU Gateway Information Vector 


Size 
Comments Offset (Bytes) Description 
0 1 Length of vector data (excluding this field) 


Note: If one of the name fields does not exist 
(cannot be determined at the time the exit is 
called}, the length field will be zeros and the 
length field of the next name in the GIV vector 
immediately follows. 


This is followed by the gateway node name: 


0 1 Length of gateway NCP name (m) 
1 m Name of the gateway NCP in the direction of the 
origin LU 


This is followed by a COS name: 
0 1 Length of COS name (n) 


1 n COS name for the network on the origin LU side 
of the gateway NCP identified above 


This is followed by another COS name: 
0 1 Length of COS name (p) 


1 p COS name for the network on the destination LU 
side of the gateway NCP identified above 


mvs vM Gateway Path Selection List 
This word of the parameter list points to the list of alternate gateway paths available 
for this LU-LU session. Table 20 on page 30 shows the format of this list. 


Gateway path entries are provided for all the alternate gateway paths defined by the 
GWPATH definition statements for each gateway NCP for which the gateway SSCP is 
performing gateway path selection. The gateway path entries are passed to the 
session management exit routine in the order in which they are defined to VITAM (by 
the GWPATH definition statements). However, the gateway NCP used for an 
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SSCP-SSCP session is always placed first in the list if this SSCP is in session with 
the gateway NCP. 


Note that the gateway path selection function might be processed in one SSCP to 
select a gateway for an adjacent SSCP. 


Table 20. Format of Gateway Path Selection List 


Dec 
(Hex) Size 
Comments Offset (Bytes) Description 
0 (0) 2 Total length of the gateway NCP path list 
(excluding this field). Do not use this field to 
determine the last gateway path entry. 
2 (2) 8 NETID of the adjacent SSCP. 
10 (A) 2 Number of gateway path selection entries (n). 
Use this number to determine the last gateway 
path entry. 


This header is followed by a variable number (n) of gateway path selection entries. 


0 (0) 1 Length of the following gateway path informa- 
tion (excluding this field). Use this field to 
determine the end of this path specification and 
the beginning of the next one. 


1 (1) 8 Name of the gateway NCP connecting this 
network to the adjacent network (obtained from 
the GWN operand on the GWPATH definition 
statement or determined from the SUBAREA 
operand). This field will be zeros if the GWN 
operand was not coded on GWPATH and this 
SSCP is not in session with the gateway NCP. 


9 (9) 4 Subarea address of the gateway NCP in this 
network (obtained from the SUBAREA operand 
on the GWPATH definition statement or deter- 
mined from the GWN operand). This field will 
be 0 if this SSCP is not in session with the 
gateway node and the SUBAREA operand was 
not coded on GWPATH. 


Note: If both GWN and SUBAREA are coded on 
the GWPATH definition statement, you cannot 
tell if this SSCP is in session with the gateway 
NCP. 


13 (D) 8 NETIO of the adjacent network accessed by the 
gateway NCP identified above (from ADJNET on 
the GWPATH statement). 


You can modify the selection list in the following ways: 


¢ You can reduce the number of gateway path entries in the list by decreasing the 
number of gateway path entries (bytes 10 and 11) in the gateway path selection 
list. If the exit routine returns a smaller number of alternate gateway nodes 
than that presented to it at entry (in the gateway path selection list), VTAM uses 
a list of only those entries. In its attempt to find a gateway node to use for the 
LU-LU session, VTAM searches that list of entries in the order they were 
returned to VTAM by the exit routine. 
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SSCP Name List 
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You can change the order of the gateway path entries in the list. The order of 
the entries returned to VTAM by the exit routine is the same order in which the 
gateway path entries are used to attempt LU-LU session setup. 


For a list to be correct, the following requirements must be met: 


Each returned gateway path entry must match one of the entries originally 
received. You cannot add new entries to the list. 


The number of entries returned cannot be larger than the number of entries 
received. 


The adjacent NETID field of the adjacent SSCP must remain unchanged. 


The returned gateway path list must contain at least one valid entry. 


If the list returned by the exit routine is invalid for any of the above reasons, the 
Original list that was sent to the exit routine is used. 


The address of the gateway path selection list should remain unchanged. The modi- 
fied gateway path list should use the same storage that was passed by VTAM to the 


exit routine. 


This word of the parameter list points to the list of adjacent SSCPs available for this 
LU-LU session. 


Table 21 shows the format of the SSCP name list. 


Table 21. Format of SSCP Name List 


Size 
Comments Offset (Bytes) Description 
0 2 Total length of the SSCP name list (excluding 
this field) 
2 2 Number of SSCP names in this list (n) 


This header is followed by a variable number (n) of SSCP names: 


0 8 Adjacent SSCP name 


You can modify the SSCP name list in the following ways: 


¢ You can reduce the number of SSCP name entries in the list by decreasing the 


number of SSCP name entries (bytes 2 and 3) in the SSCP name list. If the exit 
routine returns a smaller number of SSCP names than that presented to it at 
entry (in the SSCP name list), VTAM uses a list of only those entries. In its 
attempt to find an SSCP name to use, VTAM searches that list of entries in the 
order they were returned to VTAM by the exit routine. 


You can change the order of the SSCP name entries in the list. The order of the 
entries returned to VTAM by the exit routine is the same order in which the 
SSCP name entries are used. 
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For a list to be correct, the following requirements must be met: 


e Each SSCP name entry returned must match one of the entries originally 
received. You cannot add new entries to the list. 


e The number of entries returned cannot be larger than the number of entries 
received. 


e The returned SSCP name list must contain at least one valid entry. 


If the list returned by the exit routine is invalid for any of the above reasons, the 
Original list that was sent to the exit routine is used. 


The address of the SSCP name list should remain unchanged. The modified SSCP 
name list should use the same storage that was passed by VTAM to the exit routine. 


mvs vM DLU Gateway Information Vector 
The DLU gateway information vector provides the gateway NCP name and COS 
names for the gateway NCP in the direction of the destination LU. This parameter is 
set to zero if the session management exit routine is scheduled in the destination 
LU’s network, since there is no such gateway NCP. 


The format of the DLU gateway information vector shown in Table 22 is the same as 
that of the OLU. 


Table 22. Format of DLU Gateway Information Vector 


Size 
Comments Offset (Bytes) Description 
0 1 Length of vector data (excluding this field) 


This is followed by the gateway node name: 


0 1 Length of gateway NCP name (m) 
1 m Name of the gateway NCP in the direction of the 
OLU 


This is followed by a COS name: 
0 1 Length of COS name (n) 


1 n COS name for the network on the OLU side of 
the gateway NCP identified above 


This is followed by another COS name: 
0 1 Length of the following COS name (p) 


1 p COS name for the network on the DLU side of 
the gateway NCP identified above 


OLU Adjacent SSCP Vector 
The OLU adjacent SSCP vector provides the name of the adjacent SSCP in the direc- 
tion of the OLU. For INIT OTHER CD processing, this provides the name of the adja- 
cent SSCP in the direction of the ILU. 
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Table 23 shows the format of the OLU adjacent SSCP vector. 


Table 23. Format of OLU Adjacent SSCP Vector 


Dec 
(Hex) Size 
Comments Offset (Bytes) Description 
0 (0) 1 Length of vector data (excluding this field) 


This is followed by the adjacent SSCP name: 


0 (0) 1 Length of the adjacent name (q) 
1 (1) q Name of the adjacent SSCP in the direction of 
the OLU 


This word of the parameter list is set to zero if the session management exit routine 
is scheduled in the network of the OLU, since there is no OLU adjacent SSCP. 


DLU Adjacent SSCP Vector 
The DLU adjacent SSCP vector provides the name of the adjacent SSCP in the direc- 
tion of the DLU. For INIT OTHER CD processing, this provides the name of the adja- 
cent SSCP in the direction of the SLU. 


Table 24 shows the format of the DLU adjacent SSCP vector. 


Table 24. Format of DLU Adjacent SSCP Vector 


Size 
Comments Offset (Bytes) Description 
0 1 Length of vector data (excluding this field) 


This is followed by the adjacent SSCP name: 


0 1 Length of the adjacent name (q) 
1 q Name of the adjacent SSCP in the direction of 
the DLU 


Note: This word of the session management exit parameter list is set with the high 
order bit on and the remaining 31 bits off, if the session management exit routine is 
scheduled in the network of the DLU, since there is no DLU adjacent SSCP. 


mvs vm Alias-Selection-Input Parameter List 
This word of the parameter list points to the alias-selection-input parameter list for 
LU-LU sessions. 


The alias-selection-input parameter list contains information necessary for trans- 
lation and is a fixed length. Its storage is obtained during begin-function proc- 
essing. If storage cannot be obtained for the alias parameter list during the begin 
function, message IST793E is issued indicating the error and the alias selection 
function is not invoked. Depending on which information needs translation, different 
fields are filled in. 


This parameter list exists only if the SSCP is gateway-capable. To be gateway- 
capable, the start option GWSSCP = YES must be specified. 


Table 25 on page 34 shows the format of the alias-selection-input parameter. 
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Table 25 (Page 1 of 3). Alias-Selection-input Parameter List 


Dec 
(Hex) Size 
Offset (Bytes) Comment Description 
0 (0) 1 Fiags for NetView alias application 
> Oe 0 = NetView alias application is not active 
1 = NetView alias application is currently 
active 
X.. 0 = NetView alias application was never active 
1 = NetView alias application used to be active. 
This bit is only meaningful if the previous bit is 
off. 
XX XXXX Reserved 
1 (1) 7 Reserved 
Start of NAME1 information 
8 (8) 1 indicates the role of the LU in the session 
9 (9) 1 indicates the primary and secondary roles of 
the OLU and DLU 
XXXX .... indicates whether the LU is the OLU, DLU or 
unknown 
. XXXX Indicates whether the LU is the PLU, SLU, or 
unknown 
10 (A) 1 Information pertaining to the LU name relevant 
for translation 
Mogi< dees 1 = NAME‘1 is the real name 
0 = NAME1 is the alias name 
XXX XXXX Reserved 
11 (B) § Reserved 
16 (10) 8 NAME1 LU name to be translated 
24 (18) 8 NETFROM1 = Network in which NAME1 is known 
32 (20) 8 NETTO1 Network that NAME1 is to be translated to. 
Blank if exit needs to determine the network. 
Start of NAME2 [Information 
40 (28) 1 Indicates the role of the LU in the session 
41 (29) 1 Indicates the primary and secondary roles of 
the OLU and DLU 
XXXX .... indicates whether the LU is the OLU, DLU, or 
unknown 
. XXXX indicates whether the LU is the PLU, SLU, or 
unknown 
42 (2A) 1 information pertaining to the LU name relevant 
for translation 
» en 1 = NAME2 is the real name 
0 = NAME2 is the alias name 
XXX XXXX Reserved 
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Table 25 (Page 2 of 3). Alias-Selection-input Parameter List 


Dec 
(Hex) Size 
Offset (Bytes) Comment Description 
43 (2B) § Reserved 
48 (30) 8 NAME2 LU name to be translated 
56 (38) 8 NETFROM2 Network in which NAME2 is known 
64 (40) 8 NETTO2 Network that NAME2 is to‘be translated to. 
Blank if exit needs to determine the network. 
Start of COS/LOG Information 
72 (48) 8 COSNAME COS name 
80 (50) 8 LOGNAME logmode name 
88 (58) 8 NETFROM Network ID in which the name(s) are known 
96 (60) 8 NETTO Network ID to which the name(s) are to be 
translated 
Start of NAME3 information 
104 (68) 1 Indicates the role of the LU in the session 
105 (69) 1 indicates the primary and secondary roles of 
the OLU and DLU 
XXXX .... indicates whether the LU is the OLU, DLU, or 
unknown 
. XXXX indicates whether the LU is the PLU, SLU, or 
unknown 
106 (6A) 1 information pertaining to the LU name relevant 
for translation 
Koay. aioe 1 = NAMES is the real name 
0 = NAMES is the alias name 
XXX XXXX Reserved 
107 (6B) § Reserved 
112 (70) 8 NAMES LU name to be translated 
120 (78) 8 NETFROM3 Network in which NAMES is known 
128 (80) 8 NETTO3 Network that NAMES is to be translated to. 
Blank if exit needs to determine the network. 
Start of NAME4 Information 
136 (88) 1 LU type. Indicates the role of the LU in the 
session. 
137 (89) 1 indicates the primary and secondary roles of 
the OLU and DLU 
XXXX .. Indicates whether the LU is the OLU, DLU, or 
unknown 
wee XXXX indicates whether the LU is the PLU, SLU, or 
unknown 
138 (8A) 1 Information pertaining to the LU name relevant 
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Table 25 (Page 3 of 3). Alias-Selection-input Parameter List 


Dec 
(Hex) Size 
Offset (Bytes) Comment Description 

ern 1 = NAME4 is the real name 

0 = NAME4 is the alias name 

.XXX XXXX Reserved 
139 (8B) 5 Reserved 
144 (90) 8 NAME4 LU name to be translated 
152 (98) 8 NETFROM4 Network in which NAME4 is known 
160 (AO) 8 NETTO4 Network that NAME4 is to be translated to. 


Blank if exit needs to determine the network. 


Table 26 shows the constants for the alias-selection-input parameter list. 


Table 26. Constants for the Alias-Selection-input Parameter List 
Type Vaiue Description 


Settings for real name or alias name 


Bit 0 The name sent for translation is the alias name. The real 
name needs to be determined. 
Bit 1 The name sent for translation is the real name. The alias 
name needs to be determined. 
Settings for OLU or DLU 
Bit 0000 It cannot be determined whether the LU is the OLU or DLU 
Bit 0001 The LU is the origin logical unit for this session 
Bit 0010 The LU is the destination logical! unit for this session 
Settings for PLU or SLU 
Bit 0000 It cannot be determined whether the LU is the PLU or SLU 
Bit 0001 The LU is the primary logical! unit for this session 
Bit 0010 The LU is the secondary logical unit for this session 


Settings for LU role 


Hex 00 The LU is a session partner 
Hex 01 The LU is the primary printer 
Hex 02 The LU is the alternate printer 


The flags explained in offset 0 (0) (Table 25 on page 34) contain information that is 
not included in the transiate inquiry. One flag indicates whether the NetView alias 
application is currently active. The second flag indicates whether the NetView alias 
application was ever active. Use these bits to maintain system integrity. 


The parameter list contains sections labeled NAME1, NAME2, NAME3 and NAME4. 
Each of these sections include information relating to the LU names, for example: 


Which LU name is requesting translation 

Role of the LU 

Role of the PLU or SLU and OLU or DLU 

Whether a real name or alias name is being sent for translation 
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¢ Whether the network ID that the name is to be translated into is known. 


In general, if a name is included in the input list, the exit may translate the name. 
This rule holds for all names except the DLU name, where additional guidelines 


apply. 


¢ ifthe DLU name is an alias name, the exit may translate the DLU name to its 
real name and provide the owning SSCP name. 


e {ff the DLU name is a real name and VTAM invokes the alias selection function 
for a request, the exit should not translate the LU name but may return the 
owning SSCP name. (The function code and related session information indi- 
cate whether the exit was driven for a request or response.) 


e If the DLU name is a real name and VTAM invokes the alias selection function 
for a response, then the exit may translate the LU name to the alias name, but 
should not return an owning SSCP name. 


NAME‘1 is the first name to be translated. NETFROM1 is the network in which the 
name to be translated (NAME1) is known. NETTO1 is the network to which NAME1 
is to be translated. For example: 


¢ NAME1 is APPLB5 
¢ NETFROM1 is NETB 
¢ NETTO1 is NETA. 


The above values indicate that APPLB5 is the name known in NETB. APPLB5 in 
NETB must be translated to the LU name in NETA. If these values are set for the 
first name, the alias selection function may evaluate the values, and return the 
translated name in the output parameter list in field RTINNAME1. 


COSNAME is the class-of-service name to be translated. LOGNAME is the logon 
mode name to be translated. NETFROM is the network ID in which either the 
logmode name, the COS name, or both names are known. NETTO is the network ID 
to which either the logmode name, the COS name, or both names are to be trans- 
lated. For example: 


¢ LOGNAME is INTERACT 
¢ NETFROM is NETA 
e NETTO is NETB. 


INTERACT in NETA is to be translated into the logmode name as known in NETB. 
The translated jogmode name is returned in the output parameter list in RTNLOG. 


Note: {if any NETTO is unknown, VTAM requests that the network ID be provided. If 
the network ID is not returned, the translated information is ignored. 


The input constants in Table 26 on page 36 are used in the alias-selection-input 
parameter list. These bit settings indicate: 


e Whether the name to be translated is a real name or an alias name 
¢ Whether the LU is the OLU or DLU 

e Whether the LU is the PLU or SLU 

e The role of the LU. 
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mvs vm Alias-Selection-Output Parameter List 

The output parameter list is where data is returned to VTAM. A name could be 
requested to be translated, but the network ID into which the name needed to be 
translated was not known. In this case, the network ID must first be determined. 
The network ID which was determined by the alias selection function is then used to 
determine the desired names. For CDINIT, DSRLST and INIT OTHER CD processing 
for SLU information, the network ID is returned in RTNNET1. For INIT OTHER CD 
processing for PLU information, the network ID is returned in RTNNET2. If any 
names were translated, but the network ID was not known, the session fails to setup. 


Table 27 shows the alias-selection-output parameter list. 


Table 27. Alias-Selection-Output Parameter List 


Dec(Hex) Size 


Offset (Bytes) Comment Description 

0 (0) 8 RTNNAME1 The name returned by the user corresponding to 
NAME1 

8 (8) 8 RTNNAME2 ~~ The name returned by the user corresponding to 
NAME2 

16 (10) 8 RTNCOS The translated COS name 

24 (18) 8 RTNLOG The translated logmode name 

32 (20) 8 RTNSSCP1 The SSCP name determined by the exit. For 


CDINIT and DSRLST processing, this field con- 
tains the DLU owning SSCP. For INIT OTHER CD 
processing, this field contains the SLU owning 
SSCP name. 


40 (28) 8 RTNSSCP2 The SSCP name determined by the exit. For 
CDINIT and DSRLST processing, this field is not 
filled in. For INIT OTHER CD processing, this 
field contains the PLU-owning SSCP name. 


48 (30) 8 RTNNET1 The network ID if the exit was to determine it. 
See the explanation above this table. 

56 (38) 8 RTNNET2 The network ID if the exit was to determine it. 
See the explanation above this table. 

64 (40) 8 RTNNAME3S The name returned by the user corresponding to 
NAME3 

72 (48) 8 RTNNAME4 ~~ The name returned by the user corresponding to 
NAME4 


The returned information must meet the following requirements: 


¢ The real network ID (the network to translate the information into) must be 
returned if it was not sent. 


e lf areal network ID is returned, and the network to translate the names into was 
sent, the networks must be the same. The network ID cannot be altered. 


e If you indicate that information was translated, but no information was returned, 
processing continues without updating any information. The return code deter- 
mines whether the NetView alias application will be invoked. 


e The input parameter list cannot be altered. 


e Blank values are valid only for the COS and the logmode names. 
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e LU, NETID, and the owning SSCP names must be padded on the right with 
blanks. 


e If information was needed, and a network ID was returned, this network ID is 
used for the real name (if it was not known). This network ID is sent to the 
NetView alias application to determine the rest of the unknown information, if 
desired. 


¢ All names must contain 1—8 characters in the following format: 


— First character: alphabetic (A—2Z) or the national characters @, #, or $ 
— Second through eighth characters: alphanumeric (A—Z or 0—9) or the 
national characters @, #, or $. 


Note: Alphabetic characters must be in uppercase. The results of their being in 
lowercase are unpredictable. 


If the list returned by the exit routine fails to meet any of these requirements, the 
request fails, unless otherwise indicated. 


The address of the alias parameter list should remain unchanged. 


uvs vm Session Flow for Alias Selection Function 
VTAM invokes the alias selection function from a variety of places throughout 
session initiation and DSRLST processing. The following flows indicate when the 
alias selection function is invoked and for what reason. Keep in mind the following 
information while reading the flows: 


e Unless otherwise noted, the flows assume that the alias selection function does 
not return any translated names and that no host is running the NetView alias 
application. 


e {f the exit returns a translated name, subsequent hosts do not request trans- 
lation for that name. 


¢ Associated LU names do not appear if the SLU is not using an associated LU 
table. 


e All flows assume that the gateway contro! is SHARE/SHARE. If the gateway 
control is ONLY, alias invocations and RU flows vary slightly. 


Note: The session flows are numbered. Refer to the respective numbered items 
following the session flows for an explanation of the flows. 


Figure 30n page 40 shows the SLU-initiated session flow. 
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SLU-Initiated Session 
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Figure 3. Session Flow for SLU-Initiated Session 


1. VTAM passes the DLU alias name, the OLU real name, the associated LU real 
names, and the LOGMODE and COS names as known in the OLU’s network. 
The alias selection function has the option of returning the DLU real name, the 
network ID of the DLU real name, the owning SSCP of the DLU, the OLU and 
associated LU alias names as known in the DLU network, and the LOGMODE 
and COS names as known in the DLU network. 


2. See number 1. 


3. Since the session management exit routine has not returned any names, VTAM 
assumes the DLU network is NETC and the name portion of the DLU real name 
is the same as the DLU alias name. VTAM requests translations from NETA to 
NETC for the OLU alias name, the associated LU alias names, the LOGMODE 
name, and the COS name. VTAM also requests the owning SSCP for the DLU. 


4. This invocation is identical to number 3 except that no request is made for the 
owning SSCP. 
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5. VTAM drives the session management exit routine to translate the COS name 
from NETC to NETB. 


6. See number 5. 


Figure 4 shows the PLU-initiated session flow. 
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Figure 4. Session Flow for PLU-initiated Session 
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1. VTAM passes the DLU alias name, the OLU real name, and the LOGMODE name 
as known in the OLU’s network. The alias selection function has the option of 
returning the DLU real name, the network ID of the DLU real name, the owning 
SSCP of the DLU, the OLU alias name, and the LOGMODE name as known in the 
DLU network. 


2. See number 1. 


3. Since the session management exit routine has not returned any names, VTAM 
assumes the DLU network is NETC and the name portion of the DLU real name 
is the same as the DLU alias name. VTAM requests translations from NETA to 
NETC for the OLU alias name and the LOGMODE name. VTAM also requests 
the owning SSCP for the DLU. 


4. This invocation is identical to number 3 except that no request is made for the 
owning SSCP. 


5. VTAM drives the session management exit routine to translate the COS name 
from NETC to NETB, and to translate the associated LU names from NETC to 
NETA. 


6. See number 5. 


7. VTAM drives the exit routine to translate the COS name from NETB to NETA. No 
attempt is made to translate the associated LU names since this host has 
already attempted to translate them. 


8. VTAM drives the exit routine to translate the COS name from NETB to NETA, 
and to translate the associated LU names from NETC to NETA. 
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Third Party-Initiated Sessions 
Figure 5 shows the third-party-initiated session flow. 
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Figure 5. Session Flow for ILU-Initiated Session 


1. VTAM passes the PLU alias name as known in NETA. The alias selection func- 
tion has the option of returning the real name of the PLU, the network ID of the 
PLU, and the owning SSCP of the PLU. The exit routine may also return the 
LOGMODE name as known in the SLU’s real network. 


2. See number 1. 
3. See number 1. 


4. VTAM passes the DLU alias name, the OLU real name, the associated LU real 
names, and the LOGMODE and COS names as known in NETC. The alias func- 
tion has the option of returning the DLU real name, the network ID of the DLU 
real name, the owning SSCP of the DLU, the OLU and associated LU alias 
names as known in the DLU network, and the LOGMODE and COS names as 
known in the DLU network. 


5. See number 4. 


6. SSCPB assumes the DLU network ID is NETB and finds that it owns the PLU. 
VTAM requests translations from NETC to NETB for the OLU alias name, the 
associated LU alias names, the LOGMODE name, and the COS name. 
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7. VTAM drives the session management exit routine to translate the OLU alias 
name, the associated LU alias names, the LOGMODE name, and the COS name 
from NETC to NETB. 


Figure 6 shows the ILU-initiated session flow. 
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Figure 6. Session Flow for ILU-initiated Session 


1. VTAM passes the PLU alias name as known in NETA. The alias selection func- 
tion has the option of returning the real name of the PLU, the network ID of the 
PLU, and the owning SSCP of the PLU. The exit may also return the LOGMODE 
name as known in the SLU’s network. /n this case, assume the alias selection 
function has returned the PLU real name and network ID. 


2. Since VTAM has learned the PLU real name and already knows the SLU rea! 
name, VTAM drives the session management exit routine again asking for the 
PLU and SLU alias names. 


3. VTAM drives the session management exit routine for the LOGMODE name as 
known in the SLU’s network. 


4. See number 2. 


5. VTAM drives the exit routine to translate the OLU alias and the LOGMODE name 
from NETB to NETC. 


6. See number 5. 


7. VTAM drives the exit routine to translate the COS name and associated LU 
names from NETC to NETA. 
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8. See number 7. 


SLU-initiated Session with USERVAR Name 
Figure 7 shows the SLU-initiated session with USERVAR name flow. 
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Figure 7. Session Flow for SLU-Initiated Session with USERVAR name 


In this example, the APPLA initiates a session with an application named UVNAME. 
SSCPC knows that UVNAME is a USERVAR for the application named APPLC. 
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. VTAM passes the DLU alias name, the OLU real name, and the LOGMODE, 


COS, and associated LU names as known in the OLU’s network. The alias 
selection function has the option of returning the DLU real name, the network ID 
of the DLU real name, the owning SSCP of the DLU, the OLU and associated LU 
alias names as known in the DLU net, and the LOGMODE and COS names as 
known in the DLU network. 


. See number 1. 


. Since the session management exit routine has not returned any names, VTAM 


assumes the DLU network is NETC and the DLU real name is the same as the 
DLU alias name. VTAM requests translations from NETA to NETC for the OLU 
alias name, the associated LU alias names, the LOGMODE name, and the COS 
name. VTAM also requests the owning SSCP for the DLU. 


. SSCPC recognizes that UVNAME is a USERVAR for APPLC. SSCPC then drives 


the exit routine to translate the DLU real name to the DLU alias name. 


. VTAM drives the exit routine to translate the DLU real name to the DLU alias 


name. 


. See number 5. 


. SSCPA restarts the session with the new application name and drives the 


session management exit routine to translate the OLU alias name, associated 
LU alias names, the LOGMODE name, and the COS name from NETA to NETC. 


. VTAM drives the exit routine to translate the OLU alias name, the associated LU 


alias names, the LOGMODE name, and the COS name from NETA to NETC. 


. See number 8. 
10. 
17. 


VTAM drives the exit routine to translate the COS name from NETC to NETB. 


See number 10. 


Figure 8 on page 47 shows the session flow for DSRLST. 
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Figure 8. Session Flow for DSRLST 
In this example, APPLA has issued an INQUIRE OPTCD=APPSTAT for an applica- 
tion by the name of UVNAME. UVNAME is a USERVAR known in NETC as APPLC. 


1. VTAM passes the DLU alias name. The alias selection function has the option of 
returning the DLU real name, the network ID of the DLU real name, and the 
owning SSCP of the DLU. 


2. See number 1. 


3. SSCPC recognizes that UVNAME is a USERVAR for APPLC, returns the real 
name on the DSRLST RSP, and drives the session management exit routine to 
translate the DLU real name to the DLU alias name. 


4. VTAM drives the exit routine to translate the DLU real name to the DLU alias 
name. 


5. See number 4. 


Design Requirements 
Follow these procedures when writing this routine: 


e Use standard linkage. 
e Save registers 0— 14. 

Likewise, keep in mind the following restrictions when writing this routine: 
e The name of the session management exit routine must be ISTEXCAA. 


e You should code only conditional GETMAINS in this routine. You can reduce the 
possibility of VTAM abending during a storage shortage by coding conditional 
GETMAINs. 


¢ mvs All data is addressable only in 24-bit mode. 
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e The session management exit routine must be reentrant. It must be link-edited 
into the appropriate library. See “Installing VTAM Exit Routines” on page 66 for 
more information on installing the correct VTAM exit routine. 


¢ The routine operates as an internal VTAM subroutine. It operates enabled in 
pageable storage. The routine gets control in supervisor state with a VTAM 
storage key. Errors in the routine could cause damage to VTAM or system 
contro! blocks and modules. VITAM performance is degraded if the routine 
requires lengthy processing time. 


e If your installation permits parallel LU-LU sessions, the session management 
exit routine must be capable of processing more than one request for the same 
LU-LU pair. You can distinguish between these sessions using the session ID 
pointed to by word 6 of the input parameter list. 


¢ Do not invoke any function that causes a system wait to occur, including implied 
waits for 1/O operations. System waits may cause VTAM failure in some timing- 
dependent situations. 


¢ Do not use VTAM macroinstructions in the routine. 


¢ mvs This exit routine may be above the 16M line. Data is always presented 
below the line. 


e mvS VM All functions, except the end function, run under abend protection. If an 
error occurs, VTAM issues message IST793E and continues as though the exit 
routine had not been coded. 


e vse An abend of the session management exit routine causes VTAM to abend. It 
is best not to execute the abend function in this exit routine. VTAM does not 
issue message IST793E. 


Suggestions: When writing your exit routine, keep in mind that any number of 
vectors may exist and the vector lengths may be different in different releases of 
VTAM. Therefore, use the variable-length parameter list indicator to determine the 
end of the list. In addition, use the length byte to manipulate each vector in the list. 
lf any bytes are added to the vector, or any vectors to the list, you do not have to 
recode your exit routine. 


Virtual Route Selection Exit Routine 


A virtual route selection exit routine enables you to modify the ordered list of virtual 
routes as specified in the COS entry. VTAM then uses your new list of virtual routes 
to select a route for the session. 


You can write a virtual route selection routine, named ISTEXCVR, to be invoked 
before VTAM establishes any sessions between logical units and before VTAM is 
terminated (to enable it to cleanup any necessary resources). 


VTAM calls the virtual route selection exit routine when a session between a 
primary logical unit in the VTAM subarea and a logical unit in another subarea is 
about to be established. The virtual route selection exit routine is not called if both 
logical units reside in the same VTAM subarea. The exit is not called for inde- 
pendent PLUs. 


The exit routine is passed only the list of routes within the local network and is 
scheduled only within the subarea of the primary logical unit. 
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Initial Register and Parameter List Contents 
When this user-written routine gains contro}, register contents are as follows: 


Register 1: Address of a variable-length parameter list (described in 
Table 28 on page 51). 

Register 13: Address of the standard 18-fullword save area. 

Register 14: Return address. 

Register 15: Address of the entry point of this routine. 


Changing the Virtual Route Selection List 


The parameter list that VTAM sends to the virtual route selection exit routine 
includes pointers to a series of data blocks called virtual route descriptor blocks. 
Each virtual route descriptor block contains the virtual route number and trans- 
mission priority for each virtual route that is defined and operative between the 
Origin and destination subareas and within the class of service requested for the 
session. 


The exit routine can modify VTAM’s route selection process by changing the 
descriptor blocks it receives in the following manner: 


Note: In the following examples, “(*)Address” means that the high-order bit indi- 
cates this is the last entry in the list. 


¢ Reordering the original list 
Example: Virtual route exit routine receives: 


Address of VR1,TP1 descriptor block 
Address of VR2,TP2 descriptor block 
Address of VR3,TP1 descriptor block 
(*)Address of VR4,TPO descriptor block 


Virtual route exit routine reorders the list and returns to VTAM: 


Address of VR3,TP1 descriptor block 
Address of VR4,TP0 descriptor block 
Address of VR1,TP1 descriptor block 
(*)Address of VR2,TP2 descriptor block 


Now VTAM will attempt to assign the pending session to VR3, then VR4, and 
so forth. 


¢ Deleting entries from original list 
Example: Virtual route exit routine receives: 


Address of VR1,TP2 descriptor block 
Address of VR2,TPO descriptor block 
Address of VR3,TP2 descriptor block 
(")Address of VR4,TP1 descriptor biock 


VR exit routine deletes VR2,TPO from the list and returns to VTAM: 


Address of VR1,TP2 descriptor block 
00 00 00 00 (4 bytes of zeros) 

Address of VR3,TP2 descriptor block 
(*)Address of VR4,TP1 descriptor block 


Now VTAM will attempt to use VR3,TP2 if VR1,TP2 cannot be activated. 
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e Using only a portion of the list 


Example: Virtual route exit routine receives: 


Address of VR1,TP1 descriptor block 
Address of VR2,TP1 descriptor block 
Address of VR3,TPO descriptor block 
(*)Address of VR4,TP2 descriptor block 


VR exit routine sets the high-order address bit on in VR2,TP1 and returns to 
VTAM: 


Address of VR1,TP1 descriptor block 
(*)Address of VR2,TP1 descriptor block 
Address of VR3,TPO descriptor block 
Address of VR4,TP2 descriptor block 


VTAM uses only VR1,TP1 and then VR2,TP1 to establish the pending 
session. !f neither route can be activated, the session-establishment 
request is terminated because no paths are available. 


e Replacing a virtual route in the list 
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Example: Virtual route exit routine receives: 


Addresses of Descriptor Blocks Descriptor Block Contents 


VR1,TP2 descriptor block aa----= > VR1,TP2..... 
VR2,TP1 descriptor block ------- > VR2,TP1..... 
VR3,TPO descriptor block ----- > VR3,TPO..... 
(*)VR4,TPO descriptor block ——nee > VR4,TPO..... 


To replace the first entry in the virtual route list, for instance, you must over- 
write the contents of the appropriate descriptor block: 


Addresses of Descriptor Blocks Descriptor Block Contents 


(Former) VR1,TP2 descriptor —_—__- > VR6,TP1..... 
block 

VR2,TP1 descriptor block wno-ne= > VR2,TP1..... 
VR3,TPO descriptor block -—_———- > VR3,TPO..... 
(“)VR4,TPO descriptor block ------- > VR4,TPO..... 


After the replacement, the first address in the list points to the same 
descriptor block. However, this descriptor block will have been overwritten, 
and now describes VR6,TP1. VTAM attempts to use VR6,TP1 before using 
the other virtual routes in the list. 


Note that if the virtual route is invalid (defined as being outside the range 
0-7 or as having a transmission priority outside the range 0— 2) or is not 
defined between the origin and destination subareas, VTAM continues 
through the set of virtual routes, attempting to activate the next one in the 
set (VR2,TP1). Note that you cannot return more virtual route blocks than 
presented on input. The list can be shortened, but not lengthened. 


LY43-0046-01 © Copyright IBM Corp. 1884, 1990 


“Restricted Materials of IBM” Virtual Route Selection Exit Routine 
Licensed Materials — Property of IBM 


The virtual route exit routine is not scheduled for the following events: 
¢ An SSCP session is established. 


¢ An LU-LU session is established that is confined entirely to the host’s subarea. 
For example, two application programs communicating within the same host, or 
an application program communicating with a channel-attached terminal. 


e A session setup is attempted, and no defined routes, which are operational, 
exist between the origin and destination subareas. In this case, the request to 
establish a session is rejected before the exit would have been scheduled. 


Table 28 shows the parameter list for the virtual route selection exit routine. 


Table 28 (Page 1 of 2). Parameter List for the Virtual Route Selection Exit Routine 


Dec (Hex) Size 
Offset (Bytes) Description 
0 (0) 4 Address of a 1-byte reason code indicating why the exit 
routine was scheduled: 
Hex Code Reason for Scheduling 
00 To establish an LU-LU session (the first 
time) 
01 To establish an LU-LU session (not the first 
time) 
02 MVS To eStablish an LU-LU session (after an 
abend to the exit subtask) 
03 Because VTAM is terminating due to HALT 
(last time) 
04 MVS Because VTAM is terminating 
4 (4) 4 Address of a 4-byte user field’ 
8 (8) 4 Address of a 1-byte session information field: 
Bit Description 
Mies shee Pending session requires a VR that maps to 
an explicit route with an ER number of 0 
(originating in the SLU subarea and termi- 
nating in the PLU subarea) 
XXX XXXX Reserved 
12 (C) 4 Address of an 8-byte field containing the COS name associ- 
ated with this pending session establishment request? 
16 (10) 4 Address of a 12-byte field containing the origin subarea 
information and LU name? 
20 (14) 4 Address of a 12-byte field containing the destination 


subarea information and LU name? 
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Table 28 (Page 2 of 2). Parameter List for the Virtual Route Selection Exit Routine 


Dec (Hex) Size 

Offset (Bytes) Description 

24 (18) 4 This word and all subsequent words will each contain the 
address of a virtual route descriptor block“ 

Notes: 


1. The user field is initially set to zero. The exit routine may use this field (for example, to 
store the address of a dynamically obtained storage area). VTAM preserves the con- 
tents of this user field and resupplies it to the exit routine the next time it is driven. 


2. This field is padded on the right with blanks as necessary to make a total of 8 charac- 
ters. 


3. This field is 12 bytes long and contains a 4-byte subarea number in binary, followed by 
an 8-byte LU name in EBCDIC. 


4. The last word of the parameter list is indicated by the setting of the high-order bit (byte 
0, bit 0) to 1. 


Table 29 shows the format of the virtual route descriptor block. 


Table 29. Format of the Virtual Route Descriptor Block 


Dec (Hex) Size 
Offset (Bytes) Description 
0 (0) 1 VR number (0— 15) 
1 (1) 1 Transmission priority (0 — 2) 
2 (2) 1 VR status 
Hex 01 — VR not active 
Hex 02 — VR is active 
3 (3) 1 Reserved 
4 (4) 2 Current’ number of LU-LU sessions between the origin and 
destination subareas using the given VR number and trans- 
mission priority 
6 (6) 2 Current’ number of LU-LU sessions between the origin and 
destination subareas using the given VR number regard- 
less of priority 
8 (8) 2 Current’ number of all sessions between the origin and 
destination subareas using the given VR number and trans- 
mission priority 
10 (A) 2 Current’ number of all sessions between the origin and 


destination subareas using the given VR number regard- 
less of priority. 


Note: ‘Current as of the queuing of the virtual route selection request to the virtual route 
selection exit routine subtask. 
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Design Requirements 
Follow these procedures when writing the virtual route selection exit routine: 


e Use standard linkage. 
e Save registers 0— 14. 


Likewise, consider the following restrictions when writing the exit routine: 


¢ You should code only conditional GETMAINs in this routine. You can reduce the 
possibility of VTAM abending during a storage shortage by coding conditional 
GETMAINs. 


e mvs All data is addressable only in 24-bit mode. 
e The exit routine must be reentrant. 


¢ mvs vM This routine runs under a VTAM subtask to permit the exit routine to 
perform any necessary I/O or other processing without affecting the VTAM main 
task. 


e¢ vsE The routine runs under the VTAM main task. 
The exit routine will execute in the problem state with VTAM’s storage key. 


MVS VM The exit routine can set up its own ESTAE (extended specify task abnormal 
exit) environment for recovery. See MVS/Extended Architecture Supervisor Ser- 
vices and Macro Instructions or VM/SP Group Control System Macro Reference for 
more information. A SYNC interface will be used between VTAM and the exit 
routine, so that the VTAM module invoking the exit routine will be isolated from any 
ESTAE environment established by the exit routine. 


VSE An abend of the virtual route selection exit routine causes VTAM to abend. 


mvs vm Abend Processing 
If scheduled as a result of an abend of the subtask under which the exit routine exe- 
cutes, the exit routine is responsible for any cleanup or reopening of data sets that 
may be required. 


If a dynamic storage address was stored in the user field (second word of the 
parameter list [see Table 28 on page 51]), the address is not valid after the abend 
is processed. 


An abend indication may occur either for a normal route selection request or for the 
last time the exit routine is driven during VTAM termination. Also, if the subtask 
under which the exit routine runs suffers an abend during “first time” route 
selection, and the exit routine has not yet returned to VTAM, the next time the exit 
routine is driven will still be considered the “first time” (reason code hex 00). This 
is not true if the next time the exit routine is driven is for VTAM termination, in which 
case reason code hex 04 is indicated. In any case, modifications made by the exit 
routine to the user field prior to an abend are preserved for use by the exit routine 
in any cleanup or recovery actions it might perform the next time it is driven. 


To summarize the implications of the above reason code specifications: 


Hex 00: Driven for route selection (first time) 

Hex 01: Driven for route selection (nth time — normal) 

Hex 02: Driven for route selection (previous time resulted in abend) 
Hex 03: Driven for VTAM termination (last time) 
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Hex 04: Driven for VTAM termination (after abend). 


If the exit routine subtask abnormally terminates, VTAM reattaches the subtask 
unless the subtask has exceeded an abend threshold. If the abend threshold is 
exceeded, VTAM uses the default list originally supptied to the exit routine. The 
session setup undergoing route selection at the time of an abend fails. Other 
queued selection requests are presented to the reattached exit. 


Final Register Contents 
The routine must leave the register status as follows: 


Registers 0— 14: Restore these registers. 
Register 15: Must be set to zero. If a nonzero value is returned, VTAM no 
longer schedules the exit routine. 


VR Pacing Window Size Calculation Exit Routine 


This exit routine specifies the bounds for virtual route pacing windows. A virtual 
route pacing window represents the quantity of path information units (PIUs) that 
can be transmitted on a virtual route before a virtual route pacing response is 
received. This response indicates that the virtual route receiver is ready to receive 
more PIUs on the route. The exit routine is called when a virtual route is activated. 
It returns the minimum and maximum values for the window of the virtual route. 


The IBM-supplied algorithm for window size calculation works with the route pacing 
algorithm used in the network. It is appropriate for most installations and configura- 
tions. VTAM calculates the minimum and maximum sizes of virtual route pacing 
windows based on the fink protocol and the explicit route length (that is, the number 
of transmission groups in the explicit route used by the virtual route). While the 
virtual route is being used to transmit data, subarea nodes along the route request 
that the endpoints adjust the window sizes within the minimum and maximum limits 
according to traffic conditions along the route. 


However, after tuning VTAM and analyzing traffic patterns and resource capabilities, 
you may want to choose your own bounds or code a replacement routine to set the 
window sizes to different values than the ones supplied by IBM. This exit routine is 
appropriate for systems where the number of resources could vary considerably 
from one day to the next. For example, you may find one or more resources whose 
capacities are not consistently used. This may warrant increasing the window 
sizes. Decreasing the window sizes is fess likely to be useful, since network-flow 
control protocols are designed to prevent congestion, and setting window sizes too 
small could reduce traffic flow considerably. 


The logic for calculating the maximum and minimum window sizes for virtua! route 
pacing is contained in the VTAM exit routine named ISTPUCWC. 


Note: You can avold coding the VR pacing window size calculation exit routine by 
specifying default minimum and maximum window sizes using the VRPWSnn 
operand on the PATH definition statement. For more information on specifying 
virtual route pacing window sizes on the PATH definition statement, see VTAM 
Resource Definition Reference. 


For most routes, VTAM sets the minimum window size to the explicit route length 
and the maximum size to 3 times the explicit route length. However, if the virtual 
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route ends in a subarea that is adjacent to VTAM, the maximum window size is set 
to the greater of 15 or 255—16n, where n is the number of explicit routes (defined or 
operative) originating in the host and passing through and not ending in the adja- 
cent subarea. This increases the maximum window size for a route to a channel- 
attached NCP that has only a few explicit routes passing through it. 


The exit routine is called when VTAM is preparing to activate a virtual route. VTAM 
passes to it the following information: 


¢ The particular virtual route number and its transmission priority. 


¢ The number and length of the explicit route that is associated with the particular 
virtual route. 


¢ The subarea addresses of the destination and adjacent subareas. 


e The number of defined and operative explicit routes that pass through, but do 
not end in, the adjacent subarea. 


e The address of the explicit route characteristics table, which describes the 
transmission group traversed by the explicit route associated with a virtual 
route. This table determines the link protocol being used between the host and 
the adjacent node on the explicit route. (See Table 31 on page 58 for the 
format of this table.) 


The following sections provide information you need to replace or modify this 
routine. See VTAM Network Implementation Guide for details. 


Initial Register and Parameter List Contents 
When the routine gains control, register contents are as follows: 


Register 1: Address of parameter list (described in Table 30). 

Register 13: Address of a standard 18-fullword save area for use by this 
routine. 

Register 14: Return address. 

Register 15: Address of the entry point of this routine. 


Table 30 (Page 71 of 2). VR-Pacing Window-Size-Calculation Exit Routine Parameter List 


Dec (Hex) Size 
Offset (Bytes) Description 
0 (0) 4 VR identifier: 
Byte 0 = Hex 00 
Byte 1 = Hex 00 
Byte 2 = VR number 
Byte 3 = Transmission priority 
4 (4) 4 Explicit route number 
8 (8) 4 Destination subarea number 
12 (C) 4 Adjacent subarea number 
16 (10) 4 Explicit route length (this length is equal to the total 
number of transmission groups in the explicit route) 
20 (14) 4 Total number of defined or operative explicit routes that 


pass through, but do not end in, the given adjacent subarea 
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Table 30 (Page 2 of 2). VR-Pacing Window-Size-Calculation Exit Routine Parameter List 


Dec (Hex) Size 
Offset (Bytes) Description 
24 (18) 4 Address of explicit route characteristics table 


Design Requirements 
Follow these procedures when writing the routine: 


e Use standard linkage. 
e Save and restore registers 2— 14. 


Likewise, take into account the following restrictions when writing the routine: 


e The routine operates as an internal VTAM subroutine. Therefore, VTAM per- 
formance may be degraded if the routine requires lengthy processing time. 
While this routine is being executed, no new VTAM operator requests or 
requests to initiate or terminate sessions are processed by VTAM for any appli- 
cation program. System waits, including implied waits for |/O operations, 
should be avoided. Also, be aware that a program check causes VTAM to 
abend. 


¢ You should code only conditional GETMAINs in this routine. You can reduce the 
possibility of VTAM abending during a storage shortage by coding conditional 
GETMAINs. 


e mvs All data is addressable only in 24-bit mode. 


¢ This routine operates enabled in pageable storage. The routine gains control in 
supervisor state and with a supervisor storage key, so errors within the routine 
could cause damage to VTAM or system control blocks and modules. 


Final Register Contents 
The routine must leave the register status as follows on return: 


Register 0: Minimum VR window size (if register 15=0). 


Note: This value must be greater than zero and Jess than or 
equal to the maximum value specified in register 1. 


Register 1: Maximum VR window size (if register 15=0). 


Note: This value must be greater than or equal to the 
minimum value specified in register 0 and less than or equal to 


295; 
Registers 2— 14: Restore these registers. 
Register 15: Return code of zero if the minimum and maximum window size 


values are to be used by VTAM. Any nonzero return code (or 
invalid values specified in register 0 or 1) causes VTAM to 
ignore the values indicated by registers 0 and 1. Instead it 
uses a minimum window size equal to the ER length anda 
maximum window size of three times the ER length or the 
minimum and maximum window sizes that you defined on the 
PATH definition statement, if any. 


For more information on specifying virtual route pacing window sizes all the PATH 
definition statement, see VTAM Resource Definition Reference. 
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uvs Using the VR Window Size Calculation Exit Routine for IMS 


Because of the specialized use of channel-to-channel virtual routes by the IMS 
resource lock manager (RLM), you may find it useful to modify the VTAM virtual 
route window size calculation exit routine (ISTPUCWC). The RLM in one IMS 
system sends one message at a time to a correspondent IMS RLM, and waits for a 
message in response. With this level of message traffic on a virtual route, the 
virtual route window size algorithm does not indicate that a demand exists to 
increase the window size. Thus, in the absence of other message traffic flowing on 
the virtual route, the window size tends to stay at its minimum value. While this sit- 
uation does not impede throughput on the virtual route, it tends to increase the 
number of machine instructions executed by VTAM for each IMS transaction 
(because VTAM processes a virtual route pacing response for every, or nearly 
every, IMS RLM message). 


Accordingly, if a channel-to-channel virtual route between two IMS systems is not 
also used for non-IMS message traffic, the following changes may be made to the 
module to reduce the number of virtual route pacing responses sent and processed 
by VTAM in each of the IMS hosts: 


1. Insert code to recognize the destination subarea address, virtual route number, 
and transmission priority that you have defined for use between the two IMS 
systems. 


2. Then, insert code so that when the module recognizes such a virtual route, it 
sets the minimum window size to a value of 6. 


3. The maximum window size may be computed in the normal manner, but the 
output of that calculation must be checked against this new minimum and must 
not be allowed to fall below it. That is, if the maximum window size is calcu- 
lated to be less than 6, the maximum should then be set to 6. 


Notes: 


1. The source code for ISTPUCWC is not provided with the VTAM program. You 
must obtain it from microfiche. 


2. You can avoid coding the VR pacing window size calculation exit routine for IMS 
by allocating IMS-to-IMS communications to a specific virtual route and trans- 
mission priority with a unique class of service. This enables you to use the 
VRPWSxx operand. 


There are two possible ways to compute the maximum window size in the 
IBM-supplied version of the module. One is used when the destination subarea is 
the same as the adjacent subarea, and the other is used in all other cases. Both 
parts of this logic should be copied into any new section of code added to compute 
window sizes for IMS RLM routes. Again, the maximum window size values com- 
puted must be adjusted, if necessary, to be at least equal to the minimum window 
size selected. 


These changes to the module are not recommended if the IMS RLM virtual route is 
shared with other virtual route users. The message traffic of the other users should 
keep the operating window size values at acceptable levels. Table 31 on page 58 
shows the characteristics of the explicit route. 
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Table 31. Explicit-Route Characteristics Table 


Size 
Comments Offset (Bytes) Description 
0 1 Control block identifier (X'4C') 
1 1 Reserved 
2 2 Length of this table 
The transmission group entry consists of the following data: 
0 1 Control block identifier (X'4D') 
1 1 Length of entry 
2 1 Not used 
3 1 DLC protocol: 


X'01' SDLC 

X'02' channel-to-communication controller 
X'03' channel-to-channel! 

X'04' LAN attachment 


Session Accounting Exit Routine 


You should use the session management exit routine rather than an accounting exit 
routine to gather accounting information, since the session management routine 
allows you to combine session-related functions into one exit routine. The session 
management exit routine also fully supports cross-network and takeover processing. 
For example, information passed to the accounting exit routine for cross-network 
sessions may be misunderstood since LU names are not necessarily unique. The 
session management exit routine’s accounting function avoids this problem since 
additional LU information is provided to the exit in the PLU and the SLU resource 
information control vectors. (See “Session Management Exit Routine” on page 3 
for more information on its capabilities.) 


You can write a session accounting exit routine to collect statistics on the number of 
times that sessions start and end, so that the users can be charged accordingly. 


The session accounting exit routine is scheduled only in SSCPs that are in the same 
domain as one of the LUs. If both the accounting and session management exit rou- 
tines are provided within the LU’s domain, VTAM schedules both exits. (See 
“Session Management Exit Routine” on page 3 for more information on its capabili- 
ties.) 


IBM does not supply a skeleton session accounting exit routine. If you want this 
routine, you must code it in its entirety. You can use any previously written 
accounting exit routine without changes for VTAM Version 3. If you do not code this 
routine, all session accounting information is discarded. 


Initial Register Contents 
When this user-written routine gains control, register contents are as follows: 


Register 0: Hex 00000000 if a session has been established; hex FFFFFFFF if a 
session has been terminated. 


Register 7: Address of the doubleword containing the name of the PLU. 
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Register 11: Address of the doubleword containing the name of the SLU. 
Register 13: Address of the save area for use by this routine. 

Register 14: Return address. 

Register 15: Address of the entry point of this routine. 


Design Requirements 
Follow these procedures when writing this routine: 


e Use standard linkage. 
e Save registers 0-14. 


Likewise, consider the following restrictions when writing this routine: 
e The name of the module must be ISTAUCAG. 


e You should code only conditional GETMAINs in this routine. You can reduce the 
possibility of VTAM abending during a storage shortage by coding conditional 
GETMAINSs. 


¢ mvs All data is addressable only in 24-bit mode. 


e The accounting exit provides the two LU names involved in the session. You 
can write this information to System Management Facility (or an equivalent 
facility), along with the time of day. From these records, you can determine the 
session connection time. This exit does not have access to the logon data, nor 
to any VTAM or TSO control blocks. 


¢ The routine operates as an internal VTAM subroutine. Therefore, performance 
is degraded if the routine requires lengthy processing time. While this routine is 
being executed, no requests to establish or terminate a session are processed 
by VITAM. System waits, including implied waits for |/O operations, should be 
avoided. 


e This routine operates enabled in pageable storage. Because the routine oper- 
ates at VTAM’s main task dispatching priority, there is a possibility of lockout if 
a wait requires another task action. The routine gets control in supervisor state 
with a VTAM storage key, so errors within the routine could cause damage to 
VTAM or system control blocks and modules. 


¢ Do not use VIAM macroinstructions in the routine. 


e The routine is notified as part of an LU-LU session setup and takedown. Design 
the routine to process requests involving only LU-LU sessions. 


e if an application program is capable of establishing parallel sessions, the exit 
routine must be capable of processing more than one request from the same 
LU-LU pair. 


Final Register Contents 


All general-purpose registers, except register 15, must be restored. No return code 
is expected by VTAM. 
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Session Authorization Exit Routine 


You should code the session management exit routine rather than an authorization 
exit routine to authorize sessions, since the session management routine handles 
both same- and cross-network sessions and allows you to combine session-related 
functions into one exit routine. (See “Session Management Exit Routine” on page 3 
for more information on its capabilities.) 


The session authorization exit routine checks on or restricts the use of an applica- 
tion program or other LU. 


For same-network sessions, VTAM calls the session authorization routine whenever 
it receives a request to establish a session between two LUs. For example, it may 
be cailed as the result of a logon from a terminal, an automatic logon, or a VTAM 
operator logon. It is called for both the initial and all subsequent logons to a con- 
trolling application (that is, one to which the terminal is logged on automatically). 


For cross-domain sessions, the authorization exit routine in each domain (the 
domain of the PLU and of the SLU) is scheduled whenever a session is in the 
process of being established. 


The session authorization exit routine is scheduled only in SSCPs that are in the 
same domain as one of the LUs. For cross-network sessions, this means that any 
information provided to the authorization exit routine could be misunderstood, since 
an LU name is not necessarily unique. You can avoid this problem by using the 
initial and secondary authorization functions of the session management exit routine 
instead of the session authorization exit routine. 


If both the session authorization and session management exit routines exist within 
the LU’s domain, the authorization exit routine is scheduled first. If it authorizes the 
session, the session management exit routine is scheduled; otherwise, the session 
management exit routine is not scheduled and session setup is rejected. 


You might code the routine to contain a table of valid sessions against which the 
session-establishment request can be compared. For example, you can design an 
application program to establish a session with any LU, using the OPNDST 

OPTCD =ACCEPT macroinstruction in its LOGON exit routine. The authorization 
exit routine could compare the identity of any LU that attempts to establish a session 
with the application program to entries in such a table to determine whether authori- 
zation can be granted for that LU. For example, a particular LU could be authorized 
only at a particular time of day. 


IBM does not supply a skeleton session authorization routine. If you want this 
routine, you must code it in its entirety. You can use any previously written authori- 
zation routine without changes for VTAM Version 3. If you do not write an authori- 
zation exit routine, all sessions are authorized. The following sections explain how 
to code this routine. 
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Initial Register and Parameter List Contents 
When VTAM passes control to this routine, register contents are as follows: 


Register 1: Address of a parameter list 

Register 13: Address of the save area for use by this routine 
Register 14: Return address 

Register 15: Address of the entry point of this routine. 


Table 32 on page 62 lists the contents of the parameter list that VTAM passes to the 
routine. The macroinstructions and options referred to are described in VTAM Pro- 
gramming. The commands are described in VTAM Operation. 


Design Requirements 
Follow these procedures when writing this routine: 


¢ Use standard linkage. 
e Save registers 0— 14. 


Likewise, consider the following restrictions when writing this routine: 
¢ The name of the module must be ISTAUCAT. 


¢ You should code only conditional GETMAINs in this routine. You can reduce the 
possibility of VTAM abending during a storage shortage by coding conditional 
GETMAINSs. 


¢ mvs All data is addressable only in 24-bit mode. 


e The routine operates as an internal VTAM subroutine. Therefore, performance 
is degraded if the routine requires lengthy processing time. While this routine is 
being executed, no new session-establishment, session-termination, or acti- 
vation requests are processed by VTAM. System waits, including implied waits 
for I/O operations, should be avoided. 


¢ This routine operates enabled in pageable storage. Because the routine oper- 
ates at VTAM’s main task dispatching priority, there is a possibility of lockout if 
a wait requires other task action. The routine gets control in supervisor state 
and with a VTAM storage key, so errors within the routine could cause damage 
to VTAM or system control blocks and modules. 


¢ Do not use VITAM macroinstructions in the routine. 


e This routine must not modify the parameter list pointed to by register 1 
(described in Table 32 on page 62). Neither can any field pointed to from the 
parameter list be modified. 


e The routine must supply a return code to VTAM in register 15. A return code of 
zero authorizes the session to be established. Any nonzero return code means 
that the request is not authorized. If the request is not authorized, VTAM 
informs the session initiator. 
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Table 32. Parameter List for the Authorization Exit Routine 


Dec (Hex) Size 
Offset (Bytes) Description 

0 (0) 1 Reserved 

1 (1) 1 Contains a decimal number 1-— 6 that identifies the request: 
No. Request 
1 Primary LU initiated session (SIMLOGON or 

OPNDST macroinstruction with ACQUIRE 
option) 

Reserved 

Reserved 

4 Operator initiated session (Logon request initi- 
ated by the network operator by issuing a 
VARY ACT command or VARY LOGON 
command) 

5 Third party initiated session (CLSDST macroin- 
struction with PASS option). (See offset 8 for 
pointer to name of application program for 
which logon is requested.) 

6 Secondary LU initiated session (REQSESS 
macroinstruction) 

2 (2) 2 Reserved 

4 (4) 4 0 or address of doubleword with name of the LU that issued 
the request. (Not applicable if offset 1 is 4 or 5.) 

8 (8) 4 0 or address of doubleword with name of the application 
program acting as the primary end of the session. 

12 (C) 4 identifies the SLU associated with request. This field con- 
tains the address of the doubleword containing the LU 
name. 

16 (10) 2 X'0001' 


Failure of the authorization exit routine to honor requests of the type discussed 
below may cause VTAM to authorize sessions that should not be authorized. 


VTAM invokes the exit routine after the initiate request for the session is received 
by the SSCP. 


lf an application program is capable of establishing parallel sessions, the exit 
routine must be capable of processing more than one request from the same LU-LU 
pair. 


For cross-domain session-initiation requests, the authorization exit routines in each 


host (the host owning the PLU and the host owning the SLU) are called during proc- 
essing of either the initiate or cross-domain initiate requests. 
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Final Register Contents 
The routine must leave the register status as follows: 


Registers 0— 14: Restore these registers. 
Register 15: Return code of zero if the request is authorized. Any nonzero 
return code if the request is not authorized. 


vse TPRINT Processing Exit Routine 


You can write an exit routine to be invoked whenever the trace print utility (TPRINT) 
has selected a record to be formatted. This routine can be used for: 


¢ Formatting trace records (other than the formatting provided by TPRINT). 

¢ Discarding unnecessary trace records. 

e Discarding unnecessary information in trace records. 

¢ Performing data analysis or problem determination. You can analyze applica- 
tion program data flows as a whole or on particular sessions; time stamping of 
TRFILE records provides a resolution of 1/1000 second. 


There is no restriction on I/O functions you might want to perform in this exit 
routine. You can, for example, communicate with the system operator (SYSLOG) to 
obtain processing options. Or you might open a VTAM access method control block 
(ACB) and communicate with a terminal user for entry of options and printing of for- 
matted trace data. 


Note: The TPRINT exit routine can operate as a subtask of VTAM or as part of 
TPRINT when TPRINT is operating as a separate job step. When it is a subtask of 
VTAM, it can degrade VTAM performance if it requires lengthy processing time 
caused, for example, by excessive looping. This potential problem can be reduced 
by executing TPRINT as a separate job in a lower-priority partition. 


The following sections provide information you need to write this routine. 


Initial Register and Parameter List Contents 
When this user-written routine gains control, register contents are as follows: 


Register 0: 0, indicates first entry after record selection. 


1, indicates subsequent entries for more output after return code 


of 8. 
Register 1: Address of a parameter list (described in Table 33). 
Register 13: Address of the save area for use by this routine. 
Register 14: Return address. 
Register 15: Address of the entry point of this routine. 


The parameter list is shown in Table 33 on page 64. 
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Table 33. TPRINT-Processing Parameter List 


Size 
Offset (Bytes) Description 
0 4 Address of trace record (ISTTRAB) 
4 4 Address of 121-byte output buffer 
8 4 Address of formatted date and time stamp for this record: 


yy.ddd/hh:mmth 


Design Requirements 
Follow these procedures when writing this routine: 


e Use standard linkage. 
e Save registers 0— 14. 


Likewise, consider the following restrictions when writing this routine: 
¢ The name of the module must be ISTRAEUE. 


¢ You should code only conditional GETMAINs in this routine. You can reduce the 
possibility of VTAM abending during a storage shortage by coding conditional 
GETMAINs. 


e This routine operates enabled in pageable storage. It gains control in problem 
state with the user’s protection key. The routine is executed under the invoking 
program’s task, which can be the VTAM task. 


¢ When the TPRINT exit routine operates as a subtask of VTAM, it can degrade 
VTAM performance if the routine requires lengthy processing time, for example, 
if it includes excessive looping. This potential problem can be reduced by exe- 
cuting TPRINT as a separate job in a lower-priority partition. 


¢ This routine must not modify the parameter list pointed to it by register 1 (the 
12-byte area described in Table 33). Neither can the fields pointed to by word 1 
(ISTTRAB) or word 3 (time stamp) be modified. 


e The routine must supply a return code to the calling routine in register 15. See 
“Final Register Contents” for a detailed description of these return codes. In 
addition, if the return code is 4 or 8, the output buffer is assumed to contain a 
SYSLST record with a valid ASA control character in the first byte. 


¢ Do not code any VSE macroinstructions that are invalid for a subtask (for 
example STXIT). Do not use STXIT AB because TPRINT establishes its own AB 
exit which must not be prevented from executing. 


Final Register Contents 
The routine must leave the register status as follows: 


Registers 0— 14: Restore these registers. 

Register 15: Valid return codes: 
0, indicates skip this record, get the next record. 
4, indicates print output, get the next record. 


8, indicates print output, return the same record for more 
output. 
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12, indicates terminate TPRINT (no SYSLST record). 


Any other return codes indicate that standard editing is to be 
performed. 


Example of a TPRINT Exit Routine 


The flowchart in Figure 9 shows the logic for a simple TPRINT exit routine. The 
function of this routine is to format internal trace (VIT) records only and to permit 
TPRINT to perform standard formatting on all other trace records. Options initial- 
ized at label SPECIFY on the flowchart might be used, for example, to select (at 
SELECT) those types of VIT records to be formatted by this routine. 


Save registers, 
parameters 


Yes Format 
header 
line 


Initialize 
data blocking 
Deblock fields 
No next part 
of data 


SELECT 


Set X‘08’ 
in register 15 


Skip 
internal trace 


initialize own 
processing 
options 


End 
of data? 


Set X'04' 
in register 15 


Set X’08’ 
in register 15 


Is 
record for 

internal 
trace? 


Any code other than 
X'00’, X’04’, X‘08’, 
or X indicates 
standard TPRINT 
formatting for the 
record 


Restore 
registers 


Figure 9. Example of Logic for a TPRINT Exit Routine 
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Installing VTAM Exit Routines 


Except for the TPRINT processing exit routine, follow these steps to install the 
appropriate VTAM exit routines: 


1. Assemble the routines. 

2. Link-edit the routines to the appropriate VTAM library: 
MVS VM Use the libraries indicated in Table 34. 
VSE Use a private definition library. 


Table 34. MVS and VM Libraries for VTAM Exit Routines 


Exit Routine MVS Library VM Library 

Session management exit routine SYS1.VTAMLIB VTAMUSER LOADLIB' 
Virtual route selection exit routine SYS1.VTAMLIB VTAMUSER LOADLIB' 
Virtual route pacing window size SYS1.VTAMLIB VTAMUSER LOADLIB' 
calculation exit routine 

Accounting exit routine SYS1.LPALIB? DCSS? 

Authorization exit routine SYS1.LPALIB? DCSS? 

Notes: 


1. VMSee “Installing Tables and Modules in VM” on page 89 for information on 
using VMFLKED to link-edit these routines. 


2. If you place your user-written exit routine in SYS1.LPALIB, re-iPL to reformat the 
link-pack area. For details, see MVS/XA System Programming Library: Initial- 
ization and Tuning. 


3. VMIf your user-coded exit routine is in the discontiguous shared segment 
(DCSS), replace the TEXT deck for the exit routine (on the VTAM BASE disk) 
with the new copy and rebuild VTAM. 


VSE To install the TPRINT processing exit routine, catalog the routine (ISTRAEUE) 
and link-edit it with the TPRINT routine into the library where VTAM is installed. 


VM/ESA VTAM exit routines can be written to run in AMODE 31 or AMODE 24 for 
migration. VTAM calls the routine in the proper AMODE based on the link-edit attri- 
butes of the exit routine load module. 


The link-editing must be done before VTAM is started. The names of the user- 
written routines must be those shown in Table 35. 


Table 35. VTAM Module Names for Exit Routines 


VTAM Module 
Exit Routine Name 
Session management exit routine ISTEXCAA 
Virtual route selection exit routine ISTEXCVR 
Virtual route pacing window size calculation exit routine ISTPUCWC 
Accounting exit routine ISTAUCAG 
Authorization exit routine ISTAUCAT 
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Chapter 2. Defining User Modules and Tables 


This chapter discusses how to create or modify the CNM table and VITAM modules. 
It also discusses installing tables and modules in VM and logon-interpret routine 
requirements. 


Module for VTAM Constants 


VTAM provides a module, ISTRACON, that contains constants used to control func- 
tions that do not usually warrant operator modification. 


You can modify a number of VTAM functions using ISTRACON. These functions are 
discussed under the following headings: 

e “Buffer-Use (SMS) Trace Snapshot Value” on page 72 

e “Maximum RU Size for Sessions” on page 72 

e “BSC 3270 Timeout (Inoperative) Value” on page 73 

e “VR Selection Subtask Interval Analysis Block” on page 73 

e “Adjacent SSCP Message Control” on page 74 

e “Alias Name Translation Control” on page 74 

e “Switched Subarea Disconnect Timeout” on page 75 

e “Host IRN Slowdown Storage” on page 75 

¢ “NetView Trace Buffers” on page 75 

e “Maximum SSCP Rerouting Count” on page 75 

e “Directory Size of Symbol Resolution Table for the Host Network” on page 76 


e “mvs vm Directory Size of Symbol Resolution Tables for Other Networks” on 
page 78 


e “mvs Process Scheduling Services Trace Control” on page 79 

e “Size of the Host Node Table (HNT)” on page 80 

e “Size of the CID Index Table” on page 80 

¢ “EAS Value for VTAM’s Application” on page 80 

e “Maximum Subarea Number” on page 81 

e “Size of Data Used by VTAM in Dumping or Loading a Remote NCP” on page 81 
e “Session Awareness (SAW) Buffer Limit” on page 82 

e “Missing Interrupt Handling for a CTC” on page 83 

e ‘VM VSE ES/9370 Token-Ring Adapter Buffer Size" on page 83 

e “VM VSE ES/9370 Token-Ring Adapter Transmit Buffer Maximum” on page 83 
e “VM VSE ES/9370 Token-Ring Adapter Transmit Buffer Minimum” on page 83 
e “Option to Receive Dumps for INOPs” on page 83 

e “Option to Prevent MDR Recording” on page 84 
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“Individual IST530I/IST5321 Message Pair Limit” on page 84. 
“MVS/ESA SAW Data Space Limit Factor” on page 84 
“MVS/ESA SAW Data Space Packing Factor” on page 84 


“MVS/ESA PIU Data Space Limit Factor” on page 84 


Table 36 summarizes all of these constants, showing their defaults as well as their 


offsets within the module. 


Table 36 (Page 1 of 2). Default IBM Constants Module (ISTRACON) 


Dec 
Offset 
2-3 


4-5 


28 


29 


30-31 


32 — 35 


36 


37 
38 — 39 


40-41 


42 


43 
44-47 


Hex 
Offset 
2-3 


4-5 


6-7 


1C 


1D 


1E-1F 


20-23 


24 


25 
26-27 


28 — 29 


2A 


2B 
2C — 2F 


70. ~=VTAM Customization 


Field 


Name 


RACBSNAP 


RACMCPBF 


RACMLUBF 


RACINOPT 


RACABCNT 


RACABINT 


RACSSMSG 


RACALIAS 


RACSSDTO 


RACINNBL 


RACPDBFS 


RACVCNT 
RACHSRT 


RACONSRT 


RACTRFLG 


RACHNTSZ 


Default 


Value 


1000 


4096 


6144 


X'0000011E ' 


X'0004' 


X'00001AD2 ' 


X'01! 


X'FF! 


30 seconds 


X'00000000' 


X'02!' 


10 
1499 


43 


X'00' 


4080 MVS VM 
2024 VSE 


Description 


Number of requests for VTAM 
buffers between snapshot dumps 


Maximum RU size for all SSCP ses- 
sions 


Maximum RU size for LU-LU ses- 
sions 


Timeout value for a BSC 3270 
Reserved 


Number of times subtask can abend 
within the time interval 


Time interval during which 
maximum number of abends can 
occur 


Defines how adjacent SSCP table 
related messages are issued 


Used to control alias name trans- 
lations 


Switched subarea disconnect 
timeout 


Defines maximum size of virtual 
storage area used to store host IRN 
transmissions 


Maximum buffers to build fora 
NetView request 


Maximum SSCP rerouting count 


Number of entries in host SRT direc- 
tory 


MVS VM Number of entries in SRT 
directories in other networks 
VSE Reserved 


MVS Enables the generation of trace 
entries which show the interaction 
between the MVS dispatcher and 
VTAM process scheduling services 


Reserved 


Size of the host node table (HNT) 
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Dec 


Offset 


48-51 


52-55 


56 — 59 


60-77 


78-79 


80 — 83 


84 — 87 


88 — 89 


90 


91 


92 


93 


94—95 


96-99 


100 — 103 


104 — 107 


108-111 
112-115 


116-119 


Hex 


Offset 


30— 33 


34-37 


38 — 3B 


3C — 4D 


4E —4F 


50 — 53 


54— 57 


58 — 59 


SA 


5B 


5C 


SD 


5E'— SF 


60 — 63 


64-67 


68 —- 6B 


6C — 6F 
70-73 


74-77 


Field 

Name 
RACCITSZ 
RACEAS 


RACSASUP 


RACBUFSZ 


RACMXBUF 


RACMIHTM 


RACLBFSZ 


RACLTXMX 


RACLTXMN 


RACINOP 


RACSMDR 


RACNTWRE 


RACHXSRT 


RACXNSRT 


RACSAWLM 
RACSAWPK 


RACPIULM 
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Default 
Value 


4080 MVS VM 
2024 VSE 


3000'MVS VM/ESA 
50 VM VSE 


511 


912 


500 VM VSE 
2000 VM/ESA 
10000 MVS 
1800 

112 


28 


14 


X'7FFFFFFF' 


VTAM Constants 


Description 


Size of the CID index table and of 
the CONVT table (both) 


Default EAS value for VTAM’s appli- 
cation 


Maximum subareas supported in 
the network 


Reserved 


Size of request unit used by VTAM 
in taking a static dump or loading a 
remote NCP 


Maximum number of session aware- 
ness (SAW) buffers allowed 


INOP the CTC at reply-timeout plus 
this many tenths of a second 


VM VSE ES/9370 Token-ring adapter 
buffer size 


VM VSE ES/9370 Token-ring adapter 
transmit buffer maximum count 


VM VSE ES/9370 Token-ring adapter 
transmit buffer minimum count 


Indicates whether or not a dump 
should be generated whenever an 
INOP occurs 


Indicates whether VTAM should 
collect SDLC statistical MDRs in 
LOGREC 


Reserved 

Individual IST5301/IST5321 message 
pair limit 

MVS VM/ESA Number of entries in 
host SRT directory 


MVS VM/ESA Number of entries in 
SRT directories in other networks 


MVS/ESA SAW data space limit factor 


MVS/ESA SAW data space packing 
factor 


MVS/ESA PIU data space limit factor 
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Modifying the Constants Module 


The VTAM constants module may be modified by replacing values within the execut- 
able module. To do this, “zap” ISTRACON’s executable module within the appro- 
priate VTAM library: 


MVS SYS1.VTAMLIB 
vm The VTAMUSER LOADLIB 
VSE A private definition library referenced in the VTAM start procedure, 


using the appropriate system service aid: 


MVS The AMASPZAP program 
vm The ZAP command 
VSE The MSHP patch function. 


Whenever ISTRACON’s values are modified, VTAM must be restarted before the 
new values are used. 


Description of Constants 


The following sections describe each of the VTAM constants in detail, indicating 
which operating systems they are found in. 


Buffer-Use (SMS) Trace Snapshot Value 


Maximum RU Size 


ISTRACON field name: RACBSNAP 


If the SMS trace is active, VTAM takes a snapshot dump after a specified number of 
requests occur for VTAM buffers. While more frequent dumps may enable you to 
more accurately determine buffer use, frequent dumps may degrade system per- 
formance. 


The IBM-supplied default number causes a snapshot dump to be taken after every 
1000 (hex 3E8) requests. You can modify this number by changing the RACBSNAP 
field in ISTRACON. 


Specify a number from 0 to 32767 (hex 7FFF). If zero is specified, a snapshot dump 
is taken after every request (that is, it is equivalent to specifying 1). 


for Sessions 
ISTRACON field names: RACMCPBF and RACMLUBF 


You can set a maximum length for RUs in LU-LU sessions and in SSCP (SSCP-PU, 
SSCP-LU, and SSCP-SSCP) sessions. For LU-LU sessions, the maximum RU lengths 
can be changed using parameters in the BIND request and can be specified through 
the appropriate logon mode tabie entry. In the absence of such specification, VTAM 
uses a default value. VTAM uses another default value for SSCP sessions. It is 
these default values that you can change in the constants module. The defaults are 
4096 for an SSCP session and 6144 for an LU session. 


The default values should be adequate in most cases. However, if they are too 
small, devices that send RUs larger than the default value are deactivated. The 
default values should be increased if your installation has logon mode table entries 
for devices that do not specify the maximum RU size and the devices may send 
larger RUs than the default. 
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BSC 3270 Timeout (Inoperative) Value 
ISTRACON field name: RACINOPT 


VTAM keeps track of the number of general poll failures that occur for a BSC 3270 
over a specific time interval. If two failures occur within the time interval, VTAM 
treats this as an unrecoverable failure of the terminal and deactivates it. If the 
second failure occurs outside the time interval, VTAM starts the poll again, and an 
operator message is sent to report the failure, even though recovery is automat- 
ically initiated. 


The pattern of responses to general poils in your installation could require you to 
change the time interval. For example, if a small number of operator messages 
report polling failures, this might suggest that the terminal responds frequently 
enough to general polls so that it would not be efficient to deactivate the terminal. Sf 
two of these failures occurred within the specified time interval, however, the device 
would be deactivated unnecessarily. In this case, you might want to decrease the 
time interval, thus decreasing the chance that the terminal is unnecessarily deacti- 
vated. 


Conversely, if general poll failures outside the time limit are frequently reported, 
you might want to increase the time interval, so that the device is deactivated 
earlier and corrective action can be initiated. 


The IBM-supplied default for the time interval is approximately 300 seconds. Thus, 
if two failures occur within 300 seconds, the 3270 is deactivated. By changing 
RACINOPT, you can specify a different time interval. 


The value in RACINOPT is specified in units of time. Each unit of time is 1.048576 
seconds. The default is hex 11E units of time, or approximately 300 seconds. The 
value can range from 0 to 2147483647 (hex 84E1FFFF). If zero is specified, the 
device is never deactivated as a result of a general poll failure. 


VR Selection Subtask Interval Analysis Block 
ISTRACON field names: RACABCNT and RACABINT 


The first field used (at offset hex 16) indicates the number of times the subtask can 
abend within the time interval. This value may be specified in the range of 0 — 32767 
(hex 7FFF). If zero is specified, there is no limit; that is, VTAM continues to reattach 
the subtask as often as it abends. 


The field at offset hex 18 is the time interval in which the maximum number of 
abends can occur. This interval is specified in units of 0.262144 seconds. The 
default is approximately 30 minutes. 


The time interval may be specified in the range of 0 — 2147483647 (hex 84E1FFFF). If 
0 is specified, VITAM does not consider the time interval in deciding whether or not 
to reattach the subtask. For example, if the count is 10 and the time interval is 0, 
VTAM stops reattaching the subtask after 10 abends. 


Ordinarily, VTAM reattaches the subtask each time it abends. If the number of 


abends exceeds the maximum within the time interval, however, VTAM no longer 
reattaches the subtask. 
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If these constants are not appropriate to your needs, you may want to change them. 
However, you should use low enough values to avoid a possible abend loop, where 
an abend is caused by a programming error within your routine. 


Adjacent SSCP Message Control 
ISTRACON field name: RACSSMSG 


This constant controls the display of messages that are generated whenever 
session initiation requests to or from adjacent SSCPs fail. It may not be desirable to 
have adjacent SSCP-related messages issued in every SSCP. These messages are 
not “duplicates” and, consequently, cannot be suppressed by the use of VTAM’s 
duplicate message ID table. 


IST8941, IST895! and IST896I may be controlled using the RACSSMSG constant. 
These messages are issued when a session initiation fails because trial and error 
routing using an adjacent SSCP table has exhausted the table. All adjacent SSCPs 


were tried but the destination LU was not located by any of the SSCPs. 


The following values may be specified for the RACSSMSG constant: 


Hex Value Description 
00 Do not issue adjacent SSCP messages in any SSCP 
01 Issue adjacent SSCP messages in SSCP (OLU) only 
02 Issue adjacent SSCP messages in all SSCPs. 


The default value is hex 01. 


Any value of the RACSSMSG constant specified other than hex 00, hex 01, or hex 02 
results in an error default value of hex 00 being used. 


The specified value is only meaningful if the host’s role is OLU. 


Alias Name Translation Control 
ISTRACON field name: RACALIAS 


This constant controls alias name translation. 


The following bit values may be specified for the RACALIAS constant: 


Bit 
Value Description 
Mice ews If ON, determine alias names 
Mie- stax if ON, determine real names 
see. ware If ON, determine owning SSCP name 
ee dere If ON, determine COS names 
ee oes if ON, determine fogmodes 
ewe Kars if ON, determine associated LU alias names 
esate. coh li Reserved. 


The default value is hex FF. 


Valid values are hex 03—FF. Any invalid value of the RACALIAS constant specified 
results in the default value of hex FF being used. 
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Switched Subarea Disconnect Timeout 
ISTRACON field name: RACSSDTO 


This parameter indicates the number of seconds that can pass, without a new LU-LU 
session beginning, before VIAM automatically disconnects the switched PU. The 
default value is 30 seconds. 


For more on automatic disconnection, see VTAM Network Implementation Guide. 


Host IRN Slowdown Storage 
ISTRACON field name: RACINNBL 


This constant defines the maximum size, in bytes, of the virtual area in VTAM 
storage that can save host intermediate routing node (IRN) transmissions. This 
pageable data area is used only when an adjacent subarea is not accepting traffic 
(for example, an NCP that has gone into slowdown mode and is not receiving data). 
Any host IRN traffic for that subarea is moved from fixed !/O buffers to the VTAM 
pageable buffers. 


If the iBM-supplied default of zero is used, the amount of storage is unlimited. 


NetView Trace Buffers 
ISTRACON field name: RACPDBFS 


This constant specifies the number of buffers to build for a session monitor request. 
The valid range is 2— 255. The default value is 2. 


Maximum SSCP Rerouting Count 
ISTRACON field name: RACVCNT 


The maximum SSCP rerouting count is the maximum number of SSCPs on a specific 
path that is searched for the destination SSCP before alternate paths are tried. If all 
paths are tried without finding the destination SSCP, the RU is not rerouted and 
VTAM sends a negative response. This constant affects the rerouting of both 
session initiations (CDINIT) and direct search routing (INQUIRE APPSTAT). 


For example, assume that this constant has been changed to 3. In Figure 10 on 
page 76, a CDINIT is sent from SSCP1 to SSCP2. SSCP2 decrements the rerouting 
count to 2 and passes the request to SSCP3, which decrements the count to 1 and 
passes the request to SSCP4. At SSCP4 the count is decremented to zero, and the 
request can go no further on that particular path; it cannot be rerouted to SSCP6. 
SSCP4 then sends a negative response to the CDINIT, and SSCP3 increments the 
rerouting count by one, allowing the request to be routed to SSCP5. As was the 
case at SSCP4, the rerouting count at SSCP5 is decremented to zero, and a negative 
response is returned. The rerouting count is again incremented to 1 at SSCP3. 
SSCP3 can continue to reroute the CDINIT if other potential paths exist. 
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Figure 10. Example of SSCP-Rerouting-Count Use 


Thus, you would reduce this count primarily to reduce potential logon time and 
storage use due to unnecessary adjacent SSCP rerouting. You should review the 
level of CDINIT and INQUIRE APPSTAT rerouting required for each network environ- 
ment carefully, and change the SSCP rerouting count accordingly. 


The IBM-supplied default value is 10. You can change the rerouting count by speci- 
fying a number from 0 to 255 (hex FF). Specifying 0 is equivalent to specifying 1. A 
maximum SSCP rerouting count of 1 prevents the gateway-capable? SSCP that 
receives the cross-network RU from rerouting that RU to another SSCP. 


For session initiation, a maximum of one rerouting can occur within a given 
network. At least every other rerouting must cross a network boundary. 


For other methods of resolving the problem of excessive rerouting, see the dis- 
cussion of the adjacent SSCP selection function of the session management exit 
routine on page 15. 


Directory Size of Symbol Resolution Table for the Host Network 


ISTRACON field name: RACHSRT (mvs vma/EsA RACHXSRT) 


The symbol resolution table (SRT) consists of an internal VTAM table used primarily 
to find information about control blocks. For a VTAM started as gateway-capable 
and interconnected with other networks, the SRT is several tables: one for the host 
network and one for each network known by VTAM. Each symbolic name has two 
parts. The first is a network ID (one assigned to each network) that finds an SRT 
directory. After the SRT directory is found, the second part of the symbolic name 
points to the address of a queue of SRT entries. 


This field specifies the number of queue pointers in the SRT directory for the 
network containing the VTAM host node. The IBM-supplied default value is 1499. 
You can change the number of SRT entry queues by specifying a number from 0 to 
32767 (hex 7FFF). If you specify 0, VTAM uses the default value of 1499. 


Note: For networks with a large number of LUs, increasing this number shortens 
the length of the queues, thereby decreasing the logon time. 


2 To be gateway-capable, an SSCP must be started with both NETID and SSCPNAME specified. GWSSCP= YES must also be speci- 


fied. 
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MVS VM/ESA RACHXSRT allows a 31-bit value for the number of SRT entry queues. If 
it contains a nonzero value, it is used instead of RACHSRT. 


There are several facts you should consider before changing the default directory 
size: 


1. Using a prime number of queue pointers results in a fairly even distribution of 
SRT entries to the queues. It is recommended that you choose a prime number. 


2. Besides the SRT entries for the names of network resources, add SRT entries to 
the host network’s SRT for the following: 


¢ Network JD 
— Add one SRT entry for each network known to this VTAM. 
e Class-of-service table 


— Add one SRT entry for each COS table associated with this host’s 
network by COSTAB operands in active gateway NCPs. That is, add one 
to your count of SRT entries for every COSTAB operand specified on the 
BUILD and NETWORK macroinstructions with this host’s NETID. 


— Add one SRT entry for this host’s COS table. 
e Adjacent SSCP table 


— Add one SRT entry for each destination SSCP in this host’s network that 
is specified in an active adjacent SSCP table. 


— Add one SRT entry for this network’s SSCP list. 
— Add one SRT entry for the default SSCP list. 
e Alias name 


— Add one SRT entry for each alias LU name that this VTAM host recog- 
nizes. 


e Autologon 


— Add one SRT entry for each SSCP that controls at least one LU that is 
designated as the PLU for a PLU-SLU automatic logon. 


e Network address 


— Add one SRT entry for each network address assigned to nodes in this 
VTAM domain. 


— Add one SRT entry for the real network address of each cross-domain 
resource that establishes a session through this VTAM SSCP. 


— Add one SRT entry for the alias network address of each cross-network 
resource that establishes a session through this VTAM SSCP. 


— Add one SRT entry for each alternate gateway path to other-network 
SSCPs (if the SUBAREA operand is specified on the GWPATH state- 
ment). 
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e NetView trace requests 


— Add one SRT entry for each resource for which there may be pending 
NetView trace requests outstanding at any one time. 


This SRT entry represents a NetView trace request that is pending fora 
resource that is not yet defined to VTAM. An example of this kind of 
undefined resource is a dynamically defined cross-domain resource for 
which no session is active at the time of the trace request. To deter- 
mine how many entries may be needed for these pending traces, you 
should know how the NetView program is used in your installation, and 
be aware of the kinds of resources in your configuration that may be 
undefined to VTAM at the time of a NetView trace request. 


Note: This value should represent the maximum number of resources 
for which there may be pending NetView trace requests outstanding at 
any one time, not the total number of resources for which a NetView 
trace may be requested. 


e PCID 
— Add one SRT entry for each LU-LU session. 
e Physical unit services control block 


For each active connection to a physical unit channel-attached to this VTAM 
host: 


— Add one SRT entry for the link. 
— Add one SRT entry for the station. 


In addition, if the PU is a subarea node (for example, a communication con- 
troller or a channel-to-channel attachment to a host), 


— Add one SRT entry for that subarea node. 


mvs vm Directory Size of Symbol Resolution Tables for Other Networks 
ISTRACON field name: RACONSRT (mvs va/esa RACXNSRT) 


This field specifies the number of queue pointers in every SRT directory for net- 
works other than this VTAM network (that is, all networks with a NETID other than 
the NETID of this VTAM specified on the BUILD and NETWORK macroinstructions 
which are included in the NCP deck). The IBM-supplied default value is 43. You can 
change the number of SRT entry queues in each directory by specifying a number 
from 0 to 32767 (hex 7FFF). If you specify 0, VTAM uses the default value of 43. It is 
recommended that you use a prime number of queue pointers. 


Note: For networks with a large number of LUs, increasing this number shortens 
the length of the queues, thereby decreasing the logon time. 


Mvs véM/ESA RACXNSRT allows a 31-bit value for the number of queue pointers in 
every SRT directory for networks other than this VTAM network. If it contains a 
nonzero value, it is used instead of RACONSRT. 
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The following are the SRT entry types in the SRT tables for each network: 
e Class-of-service table 


— Add one SRT entry for each COS table associated with another network by 
COSTAB operands in active gateway NCPs. That is, add one to your count 
of SRT entries for every COSTAB operand specified on the BUILD and 
NETWORK macroinstructions with NETIDs other than that of this host. 


¢ Adjacent SSCP table 


— Add one SRT entry for each destination SSCP in another network specified 
in an active adjacent SSCP table. 


— Add one SRT entry for each default adjacent SSCP list for the other net- 
works. 


e Network address 


— Add one SRT entry for the real network address of each cross-network 
resource that establishes a session through this VTAM SSCP. 


— Add one SRT entry for the alias network address of each host-network 
resource that establishes a session through this VTAM SSCP. 


— Add one SRT entry for each alternate gateway path to other-network SSCPs 
(if the ADJNETSA operand is specified on the GWPATH statement). 


¢ SSCPID 


— Add one SRT entry for each other-network SSCP that has a session with this 
VTAM SSCP. 


e PCID 
— Add one SRT entry for each LU-LU session. 
¢ Nodes 
— Add one SRT entry for each active CDRSC in another network. 


mvs Process Scheduling Services Trace Control 
ISTRACON field name: RACTRFLG 


The trace entries that show the interaction between the MVS dispatcher and the 
process scheduling services (PSS) component of VTAM are normally not generated 
when using the VTAM internal trace (VIT) with OPTION=PSS or OPTION=ALL spec- 
ified. The zappable constant RACTRFLG enables all or some of these entries to be 
optionally generated during VIT processing. The VTAM internal trace must have 
OPTION=PSS or OPTION =ALL active to allow the optional entries to be generated. 
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The following values may be specified for the RACTRFLG constant: 


Value Description 

X'00' Do not include IRB or SRB entries in VTAM internal trace 
X'40' Include IRB entries in VTAM internal trace 

X'80' Include SRB entries in VTAM internal trace 

X'CO' Include IRB and SRB entries in VTAM internal trace. 


The default value is hex 00. 


Any value of the RACTRFLG constant specified other than hex 00, hex 40, hex 80, or 
hex CO results in the default value of hex 00 being used. 


Size of the Host Node Table (HNT) 
ISTRACON field name: RACHNTSZ 


This field determines the maximum size of the host node table used to find element 
addresses. Each entry in this table represents an element address of the host. 
When all entries in a table are filled, a chain is created to another block of entries. 
The larger the table size, the less chaining there is and the better the performance. 
However, storage may be used less efficiently if larger tables are used. The 
minimum for correct VITAM activation is 136 bytes. If a lower value is specified, 136 
is used. The default value is MvS vM 4080 and VsE 2024. 


Size of the CID Index Table 
ISTRACON field name: RACCITSZ 


This field determines the maximum size of the following index tables, used to find 
control blocks as indicated: 


ISTCIT Function management control blocks (FMCBs). Each entry in this table 
represents the location of an FMCB that represents the session identi- 
fied by the CID value. The minimum for correct VTAM activation is 28 
bytes. If a lower value is specified, 28 is used. 


ISTCONVT Conversation control blocks (RABs). Each entry in this table repres- 
ents the location of an RAB that represents the conversation identified 
by the CID value. 


When all entries in one of these tables are allocated, a chain is created to another 
block of entries. The larger the table size, the less chaining there is and the better 
the performance. However, storage may be used less efficiently if larger tables are 
used. 


The default value is mvs vm 4080 and vse 2024. 


EAS Value for VTAM’s Application 
ISTRACON field name: RACEAS 


This field determines the maximum number of SNA network addressable units and 
channel-attached non-SNA terminals that may be active at the same time. Ifthe 
actual total number of SNA network addressable units and channel-attached 
non-SNA terminals in the VTAM system is greater than the number specified here, 
or if the actual number is greater than 8080, the VTAM path length is increased. 


The valid range is 0—32767. The default value is mvs 3000 and vm vse 50. 
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For more information on EAS values, see the VTAM Network Implementation Guide. 


Maximum Subarea Number 
ISTRACON field name: RACSASUP 


This field determines the maximum subarea number supported by a network to 
which a host running VTAM is interconnected. 


The valid values for this field are: 


255 
511 
1023 
2047 
4095 
8191 
16383 
32767 
65535. 


lf the value coded is not one of the values listed above, VTAM: 


e Assumes 65535 if the value is greater than 65535 

¢ Assumes 255 if the value is less than 255 

e Rounds up to the next higher supported value if the invalid value is between 255 
and 655385. 


Size of Data Used by VTAM in Dumping or Loading a Remote NCP 
ISTRACON field name: RACBUFSZ 


This field determines the request unit size (I/O bufsize minus the size of the SNA 
header) used by VIAM when taking a static dump of a remote NCP or when loading 
one. The default size is 512 bytes, but VTAM can also handle sizes of 1024 (hex 400) 
or 2048 (hex 800) bytes. 


The range of allowable values for this field is determined by calculating the result 
of: 
(MAXBFRU X UNITSZ) - 34 bytes 


for each of the NCPs on the path between the host and the remote NCP being 
dumped or loaded. The value you choose for this field must be Jess than the lowest 
number in this series of results. 


Notes: 


1. This constant does not apply to a MODIFY LOAD. The length of the IPLTEXT RU 
is always 2048 plus the length of the SNA header. 


2. This constant applies only to static dumps or loads of 3720, 3725, and 3745 Com- 
munication Controllers. VTAM ignores this constant when dumping or loading a 
3705 and uses a default data size of 512 bytes. 


3. This constant is equivalent to the start option NCPBUFSZ. 
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Session Awareness (SAW) Buffer Limit 
ISTRACON field name: RACMXBUF 


This field sets the maximum number of buffers used for session awareness (SAW) 
buffers. To determine whether you need to change this constant, use the following 
method: 


1. First, note the following information: 
e The size of the buffer header (buffer-header-size) is 48. 
e The buffer size (buffer-size), as you defined it through the NetView program. 
e The number of physical units (number-of-PUs), as defined on the NCP. 


e The number of dependent logical units (number-of-LUs), as defined on the 
NCP. 


e The maximum SAW record size (SAW-record-size): 


— For SSCP-PU or SSCP-LU sessions is 133 
— Within a single network is 235 
— For cross-network is 370. 


2. Then, compute the average SAW record size: 


a. The number of SSCP SAW records is obtained by adding the number of 
physical units to the number of logical units: 


SSCP-SAW-records = Number-of-PUs + Number-of-dependent-LUs 


b. The number of LU-LU SAW records is equal to the number of LUs: 
LU-LU-SAW-records = Number-of-LUs 


c. The total number of SAW records is obtained by adding the number of SSCP 
SAW records to the number of LU-LU SAW records from the last two calcu- 
lations: 


Total-SAW-records = SSCP-SAW-records + LU-LU-SAW-records 


d. The average SAW record size is derived from the following formula: 


Avg-SAW-record-size = 
((SSCP-SAW-records x 133) + 
(same-network LU-LU-SAW records x 235) + 
(cross-network LU-LU-SAW records x 370)) + Total-SAW-records) 


3. Compute the number of SAW records in a SAW buffer. To do this, subtract the 
size of the buffer header from the size of the buffer, then divide this difference 
by the average SAW record size; round down the answer obtained from this 
division: 

Records-per-buffer = 
Round-down((Buffer-size - Buffer-header-size) + Avg-SAW-record-size) 


4. Finally, determine the maximum number of buffers used when taking down an 
NCP by using the formula: 


Max imum-number-of-SAW-buffers = 
(1.25 x Total-SAW-records) + Records-per-buffer 


If the number produced by this algorithm is significantly different from the default 
value (mvs 10,000 buffers, vm vse 500 buffers), then you may want to alter this con- 
stant. 
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Missing Interrupt Handling for a CTC 
ISTRACON field name: RACMIHTM 


This value is related to missing interrupt handling by VTAM for a CTC (channel-to- 
channel). It is a time value coded in tenths of seconds. 


After CTC I/O has been started, if no reply is received in REPLYTO seconds, VTAM 
waits (RACMIHTM x .10) seconds. If no reply is received by then, the !/O is halted. 


Note: REPLYTO is a system definition parameter. 
The default value is 3 minutes. 


VM vsE Es/9370 TOken-Ring Adapter Buffer Size 
ISTRACON field name: RACLBFSZ 


This parameter sets the buffer size used in the I/O adapter for token-ring con- 
nections in an IBM 9370. This buffer size may be set to zero. If this parameter is set 
to zero, the adapter uses its default value. If the buffer size is not set to zero, it 
must be greater than or equal to 96 (hex 60) and must be a multiple of 8. The default 
value is 112. 


VM vsE Es/9370 FOken-Ring Adapter Transmit Buffer Maximum 
ISTRACON field name: RACLTXMX 


This parameter indicates the maximum number of buffers that are used as transmit 
buffers in the 1/O adapter for token-ring connections in an IBM 9370. The adapter 
always keeps a minimum of two buffers as receive buffers. If this parameter is set 
to zero, the adapter uses its default value. 


Note: The transmit buffer count, with the buffer size, is used to determine the 
maximum size frame that the adapter can transmit. The default value for the buffer 
count Is 28. 


VM VSE Es/9370 LOken-Ring Adapter Transmit Buffer Minimum 
ISTRACON field name: RACLTXMN 


This parameter indicates the number of buffers that are to be reserved as transmit 
buffers in the 1/O adapter for token-ring connections in an IBM 9370. These buffers 
are reserved as transmit buffers and are never used for receive buffers. If zero is 
specified, no buffers are reserved for transmit. The minimum transmit buffer count 
must be less than or equal to the transmit maximum buffer count. The default value 
is 14. 


Option to Receive Dumps for INOPs 
ISTRACON field name: RACINOP 


This parameter indicates whether VTAM dumps should be generated whenever 
VTAM detects certain INOPs. Any nonzero value indicates that dumps are gener- 
ated for INOPs. The default value for RACINOP is zero. 


Note: Once this field has been changed, VTAM dumps are taken for certain CTC, 
local-SNA, and channel-attached NCP INOPs. 


LY43-0046-01 © Copyright IBM Corp. 1984, 1990 Chapter 2. Defining User Modules and Tables 83 


VTAM Constants “Restricted Materials of IBM” 
Licensed Materials — Property of IBM 


Option to Prevent MDR Recording 
ISTRACON field name: RACSMDR 


This parameter indicates whether the SDLC statistical MDRs should be recorded to 
LOGREC. The default value is zero, which indicates recording will occur. To 
prevent recording, code a nonzero RACSMDR value. 


Individual IST5301/IST5321 Message Pair Limit 
ISTRACON field name: RACNTWRE 


This parameter limits the number of IST530!1 and IST532I messages that are written 
for individual subareas by the IOPD facility. 


RACNTWRE can be set to any non-negative, signed, binary, fixed-point value. If the 
number of pending I/O operations for a subarea is greater than the value of 
RACNTWRE, then the IOPD facility writes just one message pair for each type of 
pending I/O operation for that subarea, rather than one pair for each operation. 


The default value for RACNTWRE is hex 7FFFFFFF, which ensures that the IST530! 
and IST532I messages report each individual pending I/O operation. 


mvs/esA SAW Data Space Limit Factor 
ISTRACON field name: RACSAWLM 


This parameter is used to calculate the maximum buffer limit for SAW data space. 
Maximum number of SAW data space buffers equals RACSAWLM times the number 
of SAW buffers in VTAM private storage. The default value is 100. 


mvs/EsA SAW Data Space Packing Factor 
ISTRACON field name: RACSAWPK 


This parameter is used to calculate the number of SAW data space buffers to queue 
before packing SAW buffers. The packing threshold equals RACSAWPK times the 
number of SAW buffers in VTAM private storage. The default value is 0. 


mvs/esA PIU Data Space Limit Factor 
ISTRACON field name: RACPIULM 


This parameter is used to calculate the maximum buffer limit for PIU data space. 
The maximum number of PIU data space buffers equals RACPIULM times the 
number of PIU buffers in VITAM private storage. The default value is 200. 
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CNM Routing Table 


VTAM refers to a communication network management (CNM) routing table to deter- 
mine which CNM application program is to receive an unsolicited network-services 
request unit that requires further processing. An application program can embed its 
own procedure-related identifier (PRID) in each request sent to VTAM. When a reply 
to the request is returned, VTAM uses the PRID to route the reply to the application 
program. Unsolicited RUs are not responses to previous requests; they contain 
network information, but they have no PRIDs. 


IBM supplies default routing information for the following CNM application pro- 
grams: 
e The NetView program 
e Alias name translation facility (supplied by IBM as part of the NetView program) 
¢ Downstream load utility. 


This table is named ISTMGC01. The listing beginning on page 111 shows the 
current IBM-supplied CNM routing table for all systems. 


For any user-written application program to use the CNM interface to receive unso- 
licited request units, you must write a supplemental table with an entry for each RU. 
This table should be named ISTMGCOO. 


lf the application to receive this unsolicited RU has opened its ACB, this user- 
supplied table (ISTMGCOO) overrides any entries within the default CNM routing 
table (ISTMGCO01). 


installing the CNM Routing Table 


Follow these steps to install the CNM routing table: 
1. Assemble the module. 
2. Link-edit it to the appropriate VTAM library: 


e mvs SYS1.VTAMLIB or SYS1.LPALIB 
If you place your user-written module in SYS1.LPALIB, re-IPL to reformat 
the link-pack area. For details, see MVS/XA System Programming Library: 
Initialization and Tuning. 


e vm The VTAMUSER LOADLIB 
See “Installing Tables and Modules in VM" on page 89 for information on 
using VMFLKED to link-edit this module. 


¢ vse A private definition library referenced in the VTAM start procedure. 


The link-editing must be done before VTAM is started. The name of the replacement 
module must be the same as the IBM-supplied module it replaces. 
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Structure of the CNM Routing Table 


A CNM routing table consists of a 12-byte header entry and routing-table entries. 
The 12-byte header entry contains the size and number of routing table entries that 
follow it. Each routing-table entry contains the network services RU (NSRU) type to 


be routed, followed by the application program name to which the NSRU is to be 
routed. The header format is shown in Table 37. 


Table 37. Format of CNM Routing-Table Header 


Dec(Hex) Size 

Offset (Bytes) Description 
0(0) 2 Number of entries 
2(2) 2 Entry length (X'000C') 
4(4) 8 Reserved 


A CNM routing-table entry consists of 12 bytes defined as shown in Table 38. 


Table 38. Format of CNM Routing Table 


Dec(Hex) Size 
Offset (Bytes) Description 
0(0) 1 Flag byte: 
Bit 0 0 = Do not send to VTAM operator 
1 = Send to VTAM operator also 
Bit 1 0 = Embed in DELIVER RU 
1 = Do not embed in DELIVER RU 
Bits 2-7 Reserved 
1(1) Network services RU type 
4(4) 8 Application program name in EBCDIC 


Bit 0 of the flag byte specifies whether the RU is to be sent to the VTAM operator 
designated to receive unsolicited messages as well as to the CNM application 
program named in the table entry. This flag bit is supported only for requests for 
which VTAM has operator message support (that is, ROUTE-INOP). 


Bit 1 of the flag byte enables you to specify that an RU is to be sent to a user-written 
CNM application program without being embedded in a DELIVER RU. If this flag bit 
is set to 1, VTAM sends the request unit to the application program without embed- 


ding it in a DELIVER RU. If the flag bit is set to 0, the request unit is embedded in 
the DELIVER RU. 


The following types of requests can be received by an application program that uses 
the CNM interface. You should provide an entry in the table for each type of unsolic- 
ited NSRU. The network services header value listed in the following text must be 
coded in the respective entry for that NSRU type (bytes 1— 3). 
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Request Header Value 
RECMS Hex 010381 
RECFMS Hex 410384 
INIT-LOAD Hex 3F0233 
TR-INQ Hex 3F0814 
ROUTE-INOP Hex 410289 
ER-TESTED Hex 410386 
CNM Hex 810814 
NMVT Hex 41038D 


You can code more than one entry associating a single type of RU with more than 
one application program; however, no more than one program associated with that 
type of RU can be active at the same time. For example, if an application program 
associated with the RECMS RU is already active, another application program asso- 
ciated with the RECMS RU is unable to open its ACB. 


For a CNM routing table that permits either of two CNM application programs 
(CNMAPPL1 or CNMALT) to receive unsolicited requests, the following might be 


coded: 

CSECT 
HDR DC X'0004' NUMBER OF ENTRIES 

oC X'O00C' ENTRY LENGTH 

DC 8X'00' RESERVED 
ENT1 DC X'@0' RESERVED 

DC X'010381' RECMS 

DC CL8'CNMAPPL1' APPLNAME 
ENT2 DC X'Q0' RESERVED 

DC X'410384 ' RECFMS 

DC CL8'CNMAPPLI1' APPLNAME 
ENT3 DC X'@0' RESERVED 

DC X'Q10381' RECMS 

oC CL8'CNMALT  ' APPLNAME 
ENT4 DC X'@Q' RESERVED 

DC X'410384' RECFMS 

CC CL8'CNMALT ' APPLNAME 

END 


Note that in the above example, CNMAPPL1 and CNMALT have each been defined 
to receive the same type of unsolicited requests (RECMS and RECFMS). In this 
case, both application programs cannot be active (that is, have open ACBs for appili- 
cation programs whose network names are CNMALT and CNMAPPL1) at the same 
time. 


Note: if you are using a user-written alias name translation facility, you must 
include it in your CNM routing table as the receiver of the TR-INQ and ROUTE-INOP 
request units. If you are using the alias name translation facility supplied as a func- 
tion of the NetView program, the default CNM routing table already contains the 
information needed for routing. 
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Logon-interpret Routine Requirements 


When a session-establishment request is received, VTAM uses the interpret table to 
determine which application program is to be notified. This section discusses the 
logon-interpret routine requirements. 


See VTAM Resource Definition Reference for information on the following: 


e Coding logon-interpret routines (APPLID routines) 
e Interpret table macroinstructions 
e Installing and changing interpret tables. 


Entry from: VTAM to entry point routinename. 


Contents of registers at entry: 


Register 0: Length of logon message. 

Register 1: Address of first byte of logon message. (See note 3.) 
Register 2: Address of an 8-byte LU name. 

Register 13: Address of a 72-byte save area provided by VTAM. 
Register 14: Return address. 

Register 15: Address of entry point of this routine. 


Operation: The logon-interpret routine is run synchronously in pageable storage 
under the control of VTAM and not under the control of an application program. For 
the application program to receive the logon, this routine must validate the logon, 
obtain the symbolic name of the application program to receive control, and provide 
this name to VTAM. Otherwise, the routine specifies that the logon is invalid or that 
the name of the application program was not found. 


Because the logon-interpret routine operates at VTAM’s main task dispatching pri- 
ority, there is a possibility of lockout if a wait requires another task action. The 
routine gets control in supervisor state with a VTAM storage key, so errors within 
the routine could cause damage to VTAM or to system control blocks and modules. 
The logon-interpret routine must also: 


¢ Save and restore the contents of registers 2— 14 when receiving and passing 
control 


e Use re-enterable code (the routine must not store anything within itself or 
modify itself during execution) 


e Perform no I/O operations; an J/O request causes the routine to terminate abnor- 
mally. 
Notes: 


1. The logon message that is passed to the interpret routine is read-only, and 
cannot be modified. 


2. MVS All data is addressable only in 24-bit mode. 


3. For LOGON requests, VTAM again searches the interpret table, after USS trans- 
lation, looking just for the specified APPLID. After USS translation, register 1 
contains the address of the first byte of the APPLID. 
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Contents of Registers at Exit: Registers 0 and 1 contain the name of the application 
program (in EBCDIC characters) with which the LU is to establish a session: 


Register 0: First 4 characters of name (left-justified). 
Register 1: Last 4 characters of name (left-justified). 
Registers 2— 14: Restored to condition at entry. 
Register 15: Return code: 
00: Application program was found and the name placed 


in registers 0 and 1. 


Nonzero: Application program was not found and the name is 
not placed in registers 0 and 1. 


if the name of the application program contains fewer than 8 characters, use blanks 
to provide a name with 8 characters. 


installing Tables and Modules in VM 


A too! called VMFLKED is available to simplify the process of link-editing the 
modules for class-of-service tables, interpret tables, logon mode tables, USS tables, 
CNM routing tables, and VTAM constants. 


Use the following procedure to create or update one of these modules using 
VMFLKED. 


1. Copy the IBM-supplied module (ISTxxxxx ASSEMBLE) on the VTM191 disk and 
update it, or create your own ASSEMBLE file. 


2. Access the disk containing the VTAM macroinstruction libraries (the default 
is 191). 


3. Issue the command: 
GLOBAL MACLIB VTAMBLD VTAMAC 
4. Assemble the table. This creates files with file types of ‘LISTING’ and ‘TEXT’. 
5. Use VMFLKED to link-edit the text file from the assemble step: 
a. Create the input control file as VTAMUSER LKEDCTRL 


Note: This file name is arbitrary. However, it is suggested that you use 
VTAMUSER for VTAM modules. 


b. Place the following records in the file: 


%LEPARMS REUS (starts in column 1) 
INCLUDE ISTxxxxx (starts in column 2) 
NAME ISTxxxxx(R) 


c. Issue the command: 
VMFLKED VTAMUSER (PRINT 


The output is a load library named VTAMUSER LOADLIB whose load 
module name is the same as you specified above. The command also 
creates a link-edit map named VITAMUSER LKEDIT. 
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6. After the library is created, the VTAM virtual machine needs to: 


a. Access the disk containing the VTAMUSER LOADLIB. 
b. Issue a global command for the VTAMUSER LOADLIB, for example: 


GLOBAL LOADLIB VTAMUSER VTAM VSCS 
You can put this command into your EXEC that starts VTAM. 
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Writing VSCS Exit Routines for VM 


VSCS Data Manipulation Exit Routines .........................00.. 93 
Exit Routines for Keyboard/Printer and TWX Devices ................ 93 
Exit Routines for Display Devices ............... 2.00.00 200000048. 96 
Installing VSCS Data Manipulation Exit Routines ................... 97 
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Chapter 3. Writing VSCS Exit Routines for VM 


This chapter contains information specific to customizing VM/SNA console support 
(VSCS). It contains information on data manipulation exit routines for VSCS. 


VSCS Data Manipulation Exit Routines 


You can write data manipulation exit routines to customize the translation of input 
and output data streams. You can write these exit routines for two categories of 
devices: 


¢ Keyboard/printers and TWX devices 
e Display devices. 


IBM supplies a skeleton exit routine, which you must recode in order to activate the 
data manipulation feature. The following sections provide information you need to 
recode the data manipulation exit routines. Figure 11 0n page 94 shows the source 
code of the IBM-supplied skeleton exit routine. See “Installing VSCS Data Manipu- 
lation Exit Routines” on page 97 for information on installing these routines. 


Exit Routines for Keyboard/Printer and TWX Devices 


The keyboard/printer and TWX device data manipulation exit routines enable you to 
manipulate the data stream for a keyboard/printer or TWX device. The name of the 
routine that manipulates input data is DTIPDNTI. The name of the routine that 
manipulates output data is DIIPDNTO. 


Use the information in Figure 11 on page 94 when coding these exit routines. 
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DTIPXXXX CSECT 
USING *,R15 


B PROLOG BRANCH OVER IDENTIFIER 
DC AL1(15) LENGTH OF MODULE IDENTIFIER 
DC C'DTIPXXXX 89.249' MODULE IDENTIFIER 

DTIPXXXX CSECT , CSECT FOR DTIPXXXX 

PROLOG STM R14,R12,12(R13) SAVE R14-R12 IN SAVE AREA 
BALR R12,0 SET UP BASE REGISTER 


PSTART ODS OH 
USING PSTART,R12 


DROP R15 

L R14,8(,R13) GET NEW SAVE AREA ADDRESS 

ST R13,4(,R14) SET BACKWARD CHAIN POINTER 

LR R1i3,R14 SWITCH TO NEW SAVE AREA 

A R14,SIZDATAD ADDRESS OF NEXT SAVE AREA 

ST R14,8(,R13) SET FORWARD CHAIN POINTER 

USING DATAD,R13 BASE THE DATAD AREA ON REGISTER 13 


MVC 0(4,R13) ,MODNAME PUT MODULE ID IN SAVE AREA 


HHRKKKKAKKKKEKEEKEREEEEEKEKEEEEKRERKAEKREEKEREEEEEKEREEREEEKEEEEEREEERKEEEE 
* 


ss User-Coded Routine Starts Here for DTIPXXXX 
* 
tC SEP SSO CES ASELEEEE ELSES ESEERES ESTE CET EESE EEE LE EEE EERE EL EEE EE ELSE ES 
STC R15,3(,R13) PUT RETURN CODE IN SAVE AREA 
L R13,4(,R13) SWITCH TO PREVIOUS SAVE AREA 
L R14,12(,R13) RESTORE RETURN REGISTER 
LM ROO,R12,20(R13) RESTORE ROO-R12 
BR R14 RETURN TO CALLER 
DATAD DSECT DSECT FOR DYNAMIC STORAGE 
DS OF 
DS 18F SPACE FOR 18 FULLWORD SAVE AREA 
WORK1 DS CL4 USER DYNAMIC STORAGE 
WORK2 DS CL8 USER DYNAMIC STORAGE 
ENDDATAD EQU * END OF DYANAMIC STORAGE 
DTIPXXXX CSECT STATIC STORAGE IN MODULE 
DS OF 


SIZDATAD DC AL1(0) 
DC AL3(( (ENDDATAD-DATAD+7) /8)*8) DYNAMIC STORAGE LENGTH 


MODNAME OC C' XXXX' MODULE IDENTIFIER FOR DTIPXXXX 
ROO EQU 00 REGISTER 0 EQUATE 
R12 EQU 12 REGISTER 12 EQUATE 
R13 EQU 13 REGISTER 13 EQUATE 
Ri4 EQU 14 REGISTER 14 EQUATE 
R15 EQU 15 REGISTER 15 EQUATE 
DS QD 
ENDDATAS EQU * END OF STATIC STORAGE 


END DTIPXXXX 


Note: XXXX is a placeholder for the last four characters of the name of the input or output 
data manipulation exit routine. 


Figure 11. IBM-Supplied Skeleton Data Manipulation Exit Routine for VSCS 
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VSCS Data Manipulation Exit Routines 


Initial Register and Parameter List Contents 
When the routine gains control, register contents are as follows: 


Register 1: Address of parameter list (described in Table 39). 
Register 13: Address of a standard 18-fullword save area for use by this 
routine. 
Register 14: Return address. 
Register 15: Address of the entry point of this routine. 
Table 39. Parameter List for Keyboard/Printer and TWX-Device Data Manipulation Exit 
Routines 
Dec(Hex) Size 
Oftset (Bytes) Description 
0(0) 4 Address of data (in ASCII line code format) 
4(4) 4 Length of data 
8(8) 4 Device subtype: 


3767 = X‘00000001' 
2741. = X'00000002' 
TWX = X'00000003' 


Note: X'O0C00C0000' indicates no value was set for the 
TERM operand for this device. 


Design Requirements and Restrictions 
Keep in mind the following information when writing these routines: 


¢ The length of the data cannot be changed (which prevents users from transiating 
APL and TEXT data). 


¢ Data outbound to a TWX device is in the form of reverse ASCIil line codes with 
mark parity supplied by the control program. 


¢ You must follow the entry and exit linkage shown in Figure 11 0n page 94 and 


in Table 39. 


¢ The online message for TWX devices is not passed to the user exit (DTIPDNTO) 
because the data is not in reverse ASCIl format. 


Final Register Contents 


These routines must leave the register status as follows on return: 


Registers 0 — 14: 


Register 13: 


Should be returned intact. 
Points to the save area and must be the same upon return. 


In addition, DTIPDNTI and DTIPDNTO must leave register 15 with the following 


status: 


Register 15: 
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Valid return codes: 


0, VSCS translates the output data stream from ASCII to 
EBCDIC. 


8, Override VSCS translation. 


Note: !f return code 8 is used to bypass VSCS translation, the 
data must be in EBCDIC form as required by the NCP on exit 
from this routine. 
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Exit Routines for Display Devices 
IBM provides an exit routine to modify the inbound data stream for display devices 
(DTIPDDS]) and one to modify the outbound data stream for display devices 
(DTIPDDSO). If you replace these exit routines, be sure that your exit routine does 
not attempt to alter the data stream when the LU state is a VSCS internal mode. 
Similarly, be careful not to destroy user-embedded screen control commands. 


The following sections provide information needed to code these routines. 


Initial Register and Parameter List Contents 
When the routine gains control, register contents are as follows: 


Register 1: Address of parameter list (described in Table 40). 

Register 13: Address of a standard 18-fullword save area for use by this 
routine. 

Register 14: Return address. 

Register 15: Address of the entry point of this routine. 


Table 40. Parameter List for Display-Device Data Manipulation Exit Routines 


Dec(Hex) Size 
Offset (Bytes) Description 
0(0) 4 Address of data 
4(4) 4 Length of data 
8(8) 1 Device attributes: 
X'80' Alternate size available 
X'40' New APL/TEXT (3278 or 3279) 
X'1C'  Color/highlight functions: 
X'10' Extended data stream available 
X'08' Extended color available 
X'04' Extended highlight available 
9(9) 1 Character set being used: 
X'00' EBCDIC 
X'01' APL 
X'02' TEXT 
10(A) 1 LU state at time of entry 
X'80° or > A VSCS internal mode; the data stream 
should not be altered if the LU is in one of 
these states. 
11(B) 1 Not used — reserved 
12(C) 1 Screen width (VSCS uses this in console mode) 
13(D) 1 Screen depth (VSCS uses this in console mode) 
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Final Register Contents 
These routines must leave the register status as follows on return: 


Registers 0— 14: Should be returned intact. 
Register 13: Points to the save area and must be the same upon return. 
in addition, DTIPDDS! and DTIPDDSO must leave register 15 with the following 
status: 
Register 15: Valid return codes: 
0, Permit VSCS translation: VSCS translates APL or TEXT data 
streams. 


8, Override VSCS translation: VSCS does not translate APL 
and TEXT data streams. 


Installing VSCS Data Manipulation Exit Routines 


To install one of the VSCS data manipulation exit routines, you must: 


¢ Code and assemble the user exit routine, being sure to use the correct name for 
each exit routine being replaced 


e Replace the user exit routine on the merge disk, and link-edit VSCS 


¢ Activate the user exit routines by setting the option KEXIT=Y (to activate 
keyboard/printer and TWX exits), setting the option DEXIT = Y (to activate 
display exits), or setting both options. This can be done by either: 


— Starting VSCS with a PARM that specifies a DTIUSER(0—9) in which KEXIT 
and DEXIT are coded as desired, or 


— Starting VSCS, then issuing VSCS CHANGE DEXIT=Y, or VSCS CHANGE 
KEXIT = Y, or issuing both. 
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Chapter 4. Writing TSO/VTAM Exit Routines for MVS 


This chapter contains information on writing exit routines for TSO/VTAM. These 
routines can be written to: 


¢ Perform input and output editing that replaces or supplements |BM-supplied 
editing 


¢ Perform attention handling that replaces IBM-supplied attention handling 
e Provide support for terminals not supported by TSO/VTAM. 


Note: An installation must write its own terminal input manager and terminal 
output manager, in addition to exit routines IKTGETXT, IKTINX2, and IKTINX1, to 
support terminals that are not supported by TSO/VTAM. 


These exit routines are optional, but before you can use an exit routine, you must 
link-edit it with the object module that calls it. For additional information, see 
“Installing TSO/VTAM Exit Routines” on page 107. 


Note: If you do not write these exit routines, you will get unresolved external refer- 
ence messages during Jink-editing of the load modules that call them. 


To determine whether any of the input and output editing exit routines are needed, 
see the sections on the TPUT and TGET options in the appropriate TSO Guide to 
Writing a Terminal Monitor Program. 


At appropriate points during VTIOC and TCAS processing, a check is made to deter- 
mine if a particular exit routine exists. If it exists, it is called; if it does not exist, 
normal processing continues. 


The exit routines are summarized in Table 41. This chapter describes the routines 
in alphabetical sequence and states what the required input and output is for each 

routine. For information about coding your own exit routines, see VTAM Program- 

ming. 


Table 41 (Page 1 of 2). Summary of the TSO/VTAM Exit Routines 


Terminal 
Name Purpose Type Caller 
VTIOC 

IKTGETXT Edit input data Unsupported IKTVTGET 

IKTIDSX1 Replace or supplement 3270 IKT32700 
IBM-supplied output editing 

IKTIDSX2 Supplement IBM-supplied 3270 IKT3270! 
input editing 

IKTIDSX3 Supplement IBM-supplied 3270 IKT32701 
attention handling 

IKTIDSX4 Replace or supplement 3270 IKTVTGET 
IBM-supplied input editing 

IKTINX2 Initialize user-written 1/O Unsupported IKTXINIT 


managers 
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Table 41 (Page 2 of 2). Summary of the TSO/VTAM Exit Routines 


Terminal 

Name Purpose Type Caller 

IKTRTX1 Replace or supplement 3767/3770 2741 IKT37670 
IBM-supplied output editing 

IKTRTX2 Supplement IBM-supplied 3767/3770 2741 IKT37671 
input editing WTTY TWX 

IKTRTX3 Replace IBM-supplied atten- 3767/3770 IKTMLU1 
tion handling (LU1) 

IKTRTX4 Replace or supplement 3767/3770 IKTVTGET 
IBM-supplied input editing (LU1) 

IKTWTX1 Replace or supplement TWX WTTY IKTWTTYO 
iBM-supplied output editing 

TCAS 

{KTCASX1 Replace or supplement Unsupported IKTCAS31 
IBM-supplied logon error 
messages 

IKTINX1 Set terminal type and buffer Unsupported IKTCAS23 
size 


IKTCASX1 — Error Handling for Non-Supported Terminals 
You must write this routine if you want to send an error message to a terminal that 
is not supported by TSO/VTAM. IKTCAS31 calls IKTCASX1 if the maximum number 
of users is reached or if IKTCAS31 cannot obtain storage for either of the TSBs or 
the logon buffer. it also calls IKTCASX1 if the address space for this session cannot 
be obtained. 


Input from IKTCASX1 
When VTAM passes contro! to IKTCASX1, register contents are as follows: 


Register 0: Address of the message buffer. 
Register 1: Address of the message number. 
Register 10: Address of a work element, IKTWESTD (terminal type defined). 


Output from IKTCASX1 


The final register contents are as follows: 


Register 1: New request unit size. 
Register 15: Return code: 
0: IBM routine performed editing. 
Nonzero: Exit routine performed all editing. 
MSGBUF: Message buffer (contains user’s message). 


IKTGETXT — Editing on Non-Supported Terminals 
You must write this routine if you want to use a terminal not supported by 
TSO/VTAM. IKTVTGET calls IKTGETXT instead of using the IBM-supplied code at 
statement label EDIT3270 (for 3270 terminals) or EDIT3767 (for 3767 and 3770 termi- 
nals) in !IKTVTGET. IKTGETXT must scan the input data, edit it, and move the edited 
data from the input queue to the TGET requester’s data area. 
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input to IKTGETXT 
When VTAM passes contro! to IKTGETXT, register contents are as follows: 
Register 0: Address of SVRB extended save area. 
Register 1: Address of IKTIPARM. 


Output from IKTGETXT 
None. 


IKTIDSX1 — Output Editing for IBM 3270 Terminals 


You may write this routine to perform 3270 output editing in place of or in addition to 
that performed by the IBM-supplied routine IKT32700 (before IKT32700 moves the 
data from the output queue into the output request unit). 


Input to IKTIDSX1 
The input to the IKTIDSX1 routine is as follows: 


Register 1: Address of IKTOPARM. 
OPACBUFA: Current buffer address. 
OPACBUFL: Current buffer length. 


Output from IKTIDSX1 


Register 15: Return code: 
0: IBM-supplied routine 1KT32700 should perform 
editing; data is still on the output queue. 
Nonzero: Exit routine performed ali editing; portions of 
IKT32700 are bypassed. 


iKTIDSX2 — Input Editing for IBM 3270 Terminals 


You may write this routine to perform input scanning and editing in addition to that 
performed by the IBM-supplied routine IKT3270I. !f provided, IKTIDSX2 is called 
after the data is translated (if necessary) from ASCII code to EBCDIC, but before it is 
scanned for input line delimiters; it is then broken into line segments and placed on 
the input queue. 


Input to IKTIDSX2 
The input to the IKTIDSX2 routine is as follows: 
Register 1: Address of IKTMPL. 

Output from IKTIDSX2 
MPLTXTA: Address of available input data. 
MPLTXTL: Length of available input data. 


IKTIDSX3 — Attention Handler for IBM 3270 Terminals 


You may write this routine to handle attention interruptions from 3270 terminals 
during input editing instead of using the IBM-supplied routine IKTATTN. One use of 
a user-coded routine is to clear the queues conditionally (rather than uncondi- 
tionally) when an attention interruption is received. 
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Input to IKTIDSX3 
The input to the IKTIDSX3 routine is as follows: 
PSAAOLD: Address of ASCB. 
ASCBTSB: Address of TSB. 
TSBEXTNT: Address of TSB extension. 


TSBXTVWA: Address of TVWA. 


Output from IKTIDSX3 


None. 


IKTIDSX4 — TGET Edit for IBM 3270 Terminals 


You may write this routine to perform 3270 editing in place of or in addition to that 
performed by the IBM-supplied routine IKTVTGET. IKTVTGET scans for invalid data 
and 3270 control characters, and moves the data from the input queue to the TGET 
requester’s data area. You might write an edit exit routine to change TGET EDIT 
editing criteria. 


Input to IKTIDSX4 
The input to the IKTIDSX4 routine is as follows: 
Register 0: Address of IKTXSA (SVRB extended save area). 
Register 1: Address of IKTIPARM. 


Output from IKTIDSX4 
The output from the IKTIDSX4 routine is as follows: 


Register 15: Return code: 


X'00':  €xit routine performed the entire edit operation and 
moved the input data to the TGET data area. 


X'04': Exit routine performed only a data scan; the 
IBM-supplied code (EDIT3270) should perform editing. 


IKTINX1 — Logon Edit 


You must write this routine if you want to use a terminal not supported by 
TSO/VTAM. IKTCAS23 calls IKTINX1, if provided, when a logon request is encount- 
ered from a terminal other than an IBM 3270, 3767, or 3770. (If TSO/VTAM is used 
with NTO, the 2741, WITTY, and TWX Models 33 and 35 are also supported.) IKTINX1 
must verify that the terminal is supported by user-written routines (that is, a terminal 
input manager, a terminal output manager, and edit routine IKTGETXT), and it must 
provide the terminal type of hex 03, the buffer size, and the device bind image. 


Input to IKTINX1 
The input to the IKTINX1 routine is as follows: 
Register 1: Address of a parameter list containing: 


e Address of the RPL 

e Address of 1 byte (WETMTP) indicating terminal type 

e Address of 2 bytes (WETMBF) indicating terminal buffer size 
e Address of WEBIND (bind image). 
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Output from IKTINX1 
The output from the IKTINX1 routine is as follows: 


Register 15: Return code: 
X'00': Recognized terminal type; logon processing continues. 
X'04': Unrecognized terminal type; logon processing termi- 
nates. 


IKTINX2 — 1/O Manager Initialization 
You must write this routine if you want to use terminal input managers and terminal 
output managers you have written. IKTINX2 should perform the same function for 
user-coded input and output managers that module IKTIIOM performs for the 
IBM-supplied I/O managers. IKTINX2 allocates storage for and initializes the 1/O 
manager SRBs. 


Input to IKTINX2 


None. 


Output from IKTINX2 
The output from the IKTINX2 routine is as follows: 


Register 15: Return code: 
0: Successful initialization. 
Nonzero: Unsuccessfu! initialization; logon processing termi- 


nates. 


IKTRTX1 — Output Edit for IBM 3767, 3770, and 2741 Terminals 


You may write this routine to perform 3767, 2741, or 3770 output editing in place of 
or in addition to that performed by the IBM-supplied routine IKT37670 (before 
IKT37670 moves the data from the output queue to the output request unit). The 
IBM-supplied code scans data, edits it according to TPUT operands specified (EDIT, 
ASIS, or CONTROL), and provides user-specified character translation. 


Input to IKTRTX1 
The input to the IKTRTX1 routine is as follows: 


Register 1: Address of IKTOPARM. 
OPACBUFA: Current buffer address. 
OPACBUFL: Current buffer length. 


Output from IKTRTX1 
The output from the IKTRTX1 routine is as foliows: 


Register 15: Return code: 
0: IBM-supplied code should perform editing; data is 
still on the output queue. 
Nonzero: Exit routine performed the entire edit operation; the 


IBM-supplied code is bypassed. 
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IKTRTX2 — Input Edit for IBM 3767 and 3770 Terminals 


You may write this routine to perform input scanning and editing in addition to that 
performed by the IBM-supplied routine IKT3767I. If provided, IKTRTX2 is called after 
the data is translated (if necessary) from ASCII code to EBCDIC and the user- 
supplied character translation is performed on the data, but before the data is 
scanned for input line delimiters, broken into single lines, and placed on the input 


queue. 

Input to IKTRTX2 
The input to the IJKTRTX2 routine is as follows: 
Register 1: Address of IKTMPL. 
MPLTXTA: Address of buffer. 
MPLTXTL: Length of buffer. 


Output from IKTRTX2 
The output from the IKTRTX2 routine is as follows: 


MPLTXTA: Address of buffer. 
MPLTXTL: Length of buffer. 


IKTRTX3 — Attention Handler for IBM 3767 and 3770 Terminals 


You may write this routine to handle attention interruptions from 3767 or 3770 termi- 
nais instead of using the IBM-supplied routine IKTATTN. One use of a user-supplied 
attention handler might be to clear the queues conditionally (rather than uncondi- 
tionally) when an attention interruption is received. 


input to IKTRTX3 
None. 


Output from IKTRTX3 
None. 


IKTRTX4 — Edit for IBM 3767, 3770, and 2741 Terminals 
You may write this routine to perform 3767 or 3770 editing in place of or in addition 
to that performed by the 1BM-supplied routine IKTVTGET. IKTVTGET scans for 
invalid data and moves the data from the input queue to the TGET requester’s data 
area. You might write an edit exit routine to change TGET EDIT editing criteria. 


Input to IKTRTX4 
The input to the IKTRTX4 routine is as follows: 
Register 0: Address of IKTXSA (SVRB extended save area). 
Register 1: Address of IKTIPARM. 
Output from IKTRTX4 
The output from the IKTRTX4 routine is as follows: 
Register 15: Return code: 
X'O0': Exit routine performed the entire edit operation and 


moved the input data to the TGET data area. 


X'04': Exit routine performed only a data scan; the 
IBM-supplied code (EDIT3767) should perform editing. 
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IKTWTX1 — Output Edit for WITTY and TWX Terminals 


You may write this routine to perform TWX or WITY output editing in place of or in 
addition to that performed by the IBM-supplied routine IKTWTTYO. The 
IBM-supplied code scans data, edits it according to the TPUT operands specified 
(EDIT, ASIS, or CONTROL), and provides user-specified character translation. 


Input to IKTWTX1 
The input to the IKTWTX1 routine is as follows: 


Register 1: Address of IKTOPARM. 
OPACBUFA: Current buffer address. 
OPACBUFL: Current buffer length. 


Output from IKTWTX1 
The output from the IKTWTX1 routine is as follows: 


Register 15: Return code: 
0: Continue with normal editing. 
Nonzero: No further editing. 


Installing TSO/VTAM Exit Routines 


You must link-edit exit routines you have coded with the object modules that call 
them. The following table shows the calling module and load module for each exit 
routine. 


Table 42. Routine — Module Cross-Reference 
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Name Calling Module Load Module 
IKTCASX1 IKTCAS31 IKTCAS30 
IKTGETXT IKTVTGET IGCO00sC 
IKTIDSX1 IKT32700 IKTIOMO2 
IKTIDSX2 IKT32701 IKTIOM02 
IKTIDSX3 {KT32701 IKTIOMO2 
IKTIDSX4 IKTVTGET IGCo0009C 
IKTINX1 IKTCAS23 IKTCAS20 
IKTINX2 IKTXINIT IKJEFLA 
IKTRTX1 IKT37670 IKTIOMO1 
IKTRTX2 1KT37671 IKTIOMO1 
IKTRTX3 IKTIMLU1 IKTIOMO1 
IKTRTX4 IKTVTGET IGCO00SC 
IKTWTX1 IKTWTTYO IKTIOMO1 
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Appendix A. IBM-Supplied CNM Routing Table 


* /*FUNCTION: 

a 

x fk 

ISTMGCO] CSECT 
DS 


ENTRIES EQU 
* 
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CNM Routing Table 


THIS IS THE CNM ROUTING TABLE FOR IBM-SUPPLIED 


CNM APPLICATIONS. EACH ENTRY IN THE TABLE 


REPRESENTS AN APPLICATION. 


OF 

S (ENTRIES) 
X'O00C' 
XL4'00000000' 
XL4'00000000 ' 
22 


XL1'00' 
XL3'410386' 
CL8'ISTNOP ' 


XL1'00' 
XL3'410289' 
CL8'ISTNOP ' 


XL1'00' 
XL3'010381' 
CL8'BNHDSERV' 


XL1'Q0' 
XL3'010381' 
CL8'BNJDSERV' 


XL1'00' 
XL3'410384' 
CL8'BNHDSERV' 


XL1' 00! 
XL3'410384' 
CL8'BNJDSERV' 


XL1'00' 
XL3'3FQ233' 
CL8'DLUPULP ' 


XL1'00' 
XL3' 410384 ' 
CL8'AAUTSKLP' 


XL1°40' 
XL3'3F0814' 
CL8'ALIASAPL' 


NLDM R2 UNIQUE 


XL1'40' 
XL3'810814' 
CL8' BNHDSERV ' 


XL1°40' 
XL3'810814' 


NUMBER OF ENTRIES 
LENGTH OF EACH ENTRY 


RESERVED 
RESERVED 


NUMBER OF ENTRIES 


FLAG BYTE 
ER TESTED RU 


NETWORK OPERATOR SERVICES NETWORK NAME 


FLAG BYTE 
ROUTE_INOP RU 


NETWORK OPERATOR SERVICES NETWORK NAME 


FLAG BYTE 
RECMS RU 


NPDA ACB NETWORK NAME 


FLAG BYTE 
RECMS RU 


NPDA VERSION 2 ACB NETWORK NAME 


FLAG BYTE 
RECFMS RU 


NPDA ACB NETWORK NAME 


FLAG BYTE 
RECFMS RU 


NPDA VERSION 2 ACB NETWORK NAME 


FLAG BYTE 
INIT LOAD RU 


DOWNSTREAM LOAD UTILITY ACB NETWORK NAME 


FLAG BYTE 
RECFMS RU 


NLDM ACB NETWORK NAME WITHOUT NPDA 


FLAG - DO NOT IMBED IN DELIVER RU 


TRANSLATE INQUIRE RU 
ALIAS ACB NETWORK NAME 


SUPPORT 


FLAG - DO NOT IMBED IN DELIVER RU 


CNM AMRU 


NPDA ACB NETWORK NAME 


FLAG - DO NOT IMBED IN DELIVER RU 


CNM AMRU 


111 


CNM Routing Table 


END 
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DC CL8'BNJDSERV ' 

OC XL1'40' 

DC XL3'810814' 

DC CL8' AAUTSKLP' 

OC XL1'8Q' 

OC XL3'410289' 

OC CL8'BNHDSERV' 

OC XL1'80' 

OC XL3'410289' 

DC CL8'BNJDSERV' 

BC XL1'80' 

DC XL3'410289' 

DC CL8‘AAUTSKLP' 
NLOM R3 UNIQUE 

BC XL1'60' 

BC XL3'41038D' 

DC CL8'BNJDSERV' 

OC XL1'00' 

OC XL3'41038D' 

BC CL8'AAUTSKLP' 

DC XL1'00' 

DC XL3'Q10381' 

OC CL8'DSICRTR ' 

DC XL1'00°' 

DC XL3'410384' 

DC CL8'DSICRTR ' 

DC XL1'40' 

OC XL3'810814' 

BC CL8'DSICRTR ' 

OC XL1'80' 

OC XL3'410289' 

OC CL8'DSICRTR ' 

DC XL1‘00' 

DC XL3‘41038D' 

DC CL8'DSICRTR ' 

DC XL1'00' 

DC XL3'0G0000 ' 

DC CL8' 

ISTMGCO1 
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NPDA VERSION 2 ACB NETWORK NAME 


FLAG - DO NOT IMBED IN DELIVER RU 
CNM AMRU 
NLOM ACB NETWORK NAME WITHOUT NPDA 


FLAG - ALSO SEND TO NETWORK OPERATOR 
ROUTE INOP RU 
NPDA ACB NETWORK NAME 


FLAG - ALSO SEND TO NETWORK OPERATOR 
ROUTE INOP RU 
NPDA VERSION 2 ACB NETWORK NAME 


FLAG - ALSO SEND TO NETWORK OPERATOR 
ROUTE INOP RU 
NLDM ACB NETWORK NAME WITHOUT NPDA 


SUPPORT 


FLAG BYTE 
NMVT RU 
NPDA VERSION 2 ACB NETWORK NAME 


FLAG BYTE 
NMVT RU 
NLDM ACB NETWORK NAME WITHOUT NPDA 


FLAG BYTE 
RECMS RU 
NETVIEW ROUTER 


FLAG BYTE 
RECFMS RU 
NETVIEW ROUTER 


FLAG - 00 NOT IMBED IN DLV RU 
CNM RU 
NETVIEW ROUTER 


FLAG - ALSO SEND TO NOS 
ROUTE INOP RU 
NETVIEW ROUTER 


FLAG BYTE 
NMVT RU 
NETVIEW ROUTER 


END OF REFERENCED TABLE ENTRIES 


UNUSED TABLE ENTRY 
IF REFERENCED THEN ALSO UPDATE 
NUMBER OF ENTRIES COUNT 
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Appendix B. Sample Session Management Exit Routine 


This session management exit routine controls various functions associated with 
VTAM logical unit session processing. These functions include: 


¢ Gateway path selection 

e Alias name translation 

e Adjacent SSCP selection 

¢ Session authorization 

¢ Session accounting 

e Session takeover accounting. 


This sample session management exit routine is only prototype code that can be 
included in a more complete and comprehensive session management exit routine. 
The sample code illustrates how the initial session management exit routine envi- 
ronment is established, the type of information that is available in each parameter 
list for the specific sample environment, and some techniques used to examine the 
various parameter lists. The sample session management exit routine is written 
specifically for the SNA network environment illustrated in Figure 12 on page 114. 
The sample uses only the following session management exit routine functions: 


e Begin 

¢ Gateway path selection 

e Alias translation 

e Secondary session authorization 
e End. 


A portion of a final accounting function is also included, however, the code is specif- 
ically related to the alias function. The initial and final accounting functions are 
normally used to record session connection time. 


Note: The examples in this appendix are intended as an educational tool. They 
show how various functions in a session management exit routine can be used to 
control VTAM functions. The examples shown are not complete and may not work 
as presented here. 
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NETID=NET1 ‘ NETID=NET2 


Subarea 
10 


Subarea 
01 


SSCPNAME 
VTAMO1 


SSCPNAME 
G1OVTAM 


GW-NCP30 AS@CICS 


NCPO2 
Subarea 
62 


Subarea 
50 


Subarea Subarea 
03 30 


SSCPNAME 
V50CDRM 


GW-NCP40 


A66CICS 


Subarea Subarea 


04 40 
Subarea 
/ 60 
/| ‘ 
| ; SSCPNAME 
| 2 V60CDRM 
NO2L0256 
USER ; A7OIMS 
TERMINAL 
. Subarea 
* 70 
. SSCPNAME 
, V¥7@CDRM 


Figure 12. Network Environment for Sample Session Management Exit Routine 


Each time VTAM invokes the session management exit routine, the exit routine must 
perform its initial programming functions. For example, the session management 
exit routine must save the register contents into a save area provided by VTAM. 

The exit routine entry point address, which establishes the necessary routine 
addressing, is contained in register 15. 
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vsE The ABEND function in the exit routine would cause VTAM to ABEND, so it is 
advisable not to execute the ABEND function in the exit routine. The prologue code 
that performs these initial tasks follows. 


KKK HK KKK IK KKK AK KKK KK KKK K KEKE KKK KEKKKKE KEKE KKKKEKKEKEKEKEKKEKKKKKKKKREKK 


RO EQU 0 

Rl EQU ol 

R2 EQU 2 

R3 EQU 3 

R4 EQU 4 

R5 EQU 5 

R6 EQU 6 

R7 EQU 7 

RB EQU 8 

RI EQU 9 

R10 EQU 10 

R11 EQU ol 

R12 EQU 12 

R13 EU 13 

R14 EQU 14 

R15 EQU «15 

KKK KKK KA KK KK IKI KKK KEKE KEKE KEK KEKE KEKEKEKKKKKEKERERERERKEKEREKEEKEKKERERK 
: SME ROUTINE PROLOGUE 


KEKKKKKKKKKKKEKE KEKE KE KEK IKKE EKER KEKE KEKE ERE KEE REEKKEKEKEKKEEKKREKER 


ISTEXCAA CSECT 


* 


** SAVE REGISTERS IN VTAM PROVIDED SAVEAREA 


* 


STM R14,R12,12(R13) SAVE VTAM'S REGISTERS 


* 


** ESTABLISH SME ROUTINE ADDRESSABILITY 


* 


INITS1 EQU * 


LR R12,R15 ESTABLISH ADDRESSABILITY 
USING ISTEXCAA,R12 BASE REGISTER USED EQUALS R12 
B INITSIA SAVE PARAMETER LIST ADDRESS 


* 


** MODULE NAME AND ASSEMBLY DATE 
* 
DC CL8' ISTEXCAA’ CSECT NAME 
DC CL8'&SYSDATE' ASSEMBLY DATE 


*x* 


* 


INITSIA EQU * 
LR R11,R1 ADDRESS FUNCTION PARAMETER LIST 


* 


** ESTABLISH SME ROUTINE REGISTER SAVE AREA 
* 
INITSIB EQU  * 

GETMAIN R,LV=72 

LTR R15,R15 


BNZ ABEND 
INITSIC EQU * 
a R13,4(R1) BACKWARD SAVE AREA POINTER 
ST R1,8(R13) FORWARD SAVE AREA POINTER 
LR R13,R1 SME ROUTINE REGISTER SAVE AREA 
B INITS2 CONTINUE INITIALIZATION PROCESSING 
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** TERMINATE SME ROUTINE ABNORMALLY DUE TO ERRORS: 
** COMPLETION CODE=999, REASON=SMEF 


* 


ABEND ABEND 999,REASON=X'E2D4C5C6' , DUMP 


RREEKKEEKKEEEREEEEREEREEEREREREEREEHEREEEEEEEKEEKEEEKEERKEKREKEKKKKKKKEE 


Function Selection 
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VTAM invokes the session management exit routine to perform various LU-session 
processing functions. You must design the session management exit routine to 
process these functions. You indicate in the begin function which LU-session proc- 
esses require VTAM to invoke the session management exit routine. After VTAM 
invokes the session management exit routine, the routine must read the function 
code in the function parameter list to determine which LU-session processing to 
perform. 


The sample session management exit routine coding compares the exit routine 
function code to a value associated with the functions selected. The function code 
values for this sample exit routine follow: 


/ 


Function Value 
Begin X'FE‘ 
Secondary session authorization X'01' 
Gateway path selection X'04' 
Alias name transiation X'07' 
End X'FF' 


The address of the exit routine function code is always the second field in the func- 
tion parameter list. The session management exit routine examines the code and 

branches to the appropriate processing within the session management exit routine. 
The following code illustrates this technique. 


REKREKKRKEKEREREREEREREEEEREREEREEEREREERRERREERREREREEEREEREEECKEEEREEEKKEK 


INITS2 EQU * 


* 


** LOCATE EXIT ROUTINE FUNCTION CODE 


* 


L R1,4(R11) EXIT ROUTINE FUNCTION CODE ADDRESS 


* 


** EXAMINE EXIT ROUTINE FUNCTION CODE TO DETERMINE LU SESSION PROCESSING 


* 


CLI O(R1),X'FE' TEST FOR BEGIN FUNCTION 
BE BEGIN YES, BRANCH TO FUNCTION PROCESSING 
* 
CLI 6(R1),X‘O1' TEST FOR SECONDARY SESSION AUTHORIZATION 
BE SECAUTH YES, BRANCH TO FUNCTION PROCESSING 
* 
CLI O(R1),X'04' TEST FOR GATEWAY PATH SELECTION 
BE GWPATH YES, BRANCH TO FUNCTION PROCESSING 
* 
CLI O(R1),X'07' TEST FOR ALIAS NAME TRANSLATION FUNCTION 
BE ALIAS YES, BRANCH TO FUNCTION PROCESSING 
* 
CLI O(R1),X‘FF' TEST FOR END FUNCTION 
BE END YES, BRANCH TO FUNCTION PROCESSING 
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B RETURN 


* 


KREKREKKEEKEEKKEEEKREREREKEREKREEEREREEEKEREREREEERERERREEARERRERKERKKRKKEKE 


Begin Function 


The begin function is a required element in any session management exit routine. 
This function is invoked at VTAM initialization. The begin function indicates to 
VTAM the functions for which the exit routine is to be invoked. 


The fourth entry in the parameter list passed to the begin function contains the 
address of the exit routine functions. The session management exit routine must set 
the proper bit on (B'1') for each function for which VTAM is to call the routine. The 
bit settings for each of the functions associated with the sample routine follow: 


Function Value 

Secondary session authorization Byte 0, bit 1 or hex 40 
Gateway path selection Byte 0, bit 3 or hex 10 
Alias name translation Byte 1, bit 2 or hex 20 
End function Byte 0, bit 4 or hex 08 


Obtaining User Storage 


In this example, the begin function sets these indicators in the exit options field. It 
also obtains storage, using a GETMAIN macroinstruction, to maintain information 
used by the various function routines. The format of the user storage area is shown 
in Figure 13 on page 118. 


The function parameter list, which is passed by VTAM to each exit routine, contains 
the address of a user data field. This field stores the address of the storage area 
acquired by the begin function. Functions subsequently called by VTAM can then 
read the user data field. 
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DEC (HEX) 
Offset 


Q (GQ) 
4 (04) 
8 (08) 
16 (OF) 
20 (14) 
28 (1C) 
32 (20) 
36 (24) 
40 (28) 


44 (2C) 


Figure 13. User Data Storage Area Format 


Loading NETID Registration Table 


The begin function also loads a table that contains registered, valid network identi- 
fiers (NETIDs). The session management exit routine functions use this table to 
ensure that an LU session request is initiated from or directed to a registered 
network. In this example, the begin function sets an indicator in the user storage 
area to inform other exit routine functions that the table is loaded and contains valid 
entries. The format of the NETID registration table is shown in Figure 14. 


DEC (HEX) 
Offset 
0 (0) 
4 (4) 
12 (C) 


28 (F) 


Figure 14. Network Identifier (NETID) Registration Table 
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Since the begin function, which is invoked only at VTAM initialization, loads the 
table, there is no direct mechanism provided by VTAM to reload the table without 
restarting VTAM. However, there are commands that can prompt the session man- 
agement exit routine to reload the table dynamically. 


For example, when a new table is ready to be loaded, the system programmer can 
issue the following VTAM operator command to initiate a “dummy” LU session: 


VARY NET, LOGON, ID=RELOAD, LOGON=TABLE 


The command in this example is issued at the gateway VTAM (GWVTAM10). In an 
attempt to initiate the “dummy” LU session between the secondary fogical unit, 
RELOAD, and the primary logical unit, TABLE, VTAM invokes the specified session 
management exit routine functions. For example, the secondary authorization func- 
tion can determine if the session request is for the “dummy” LU session. When the 
session management exit function discovers the session setup is for the “dummy” 
LU session, the NETID registration table is reloaded. After the table is reloaded, the 
function routine can reject the session request with a proper return code to VTAM. 


The sample code below also checks the NETID registration table to ensure that the 
table entry count is not zero. If there are no entries in the table, the session man- 
agement exit begin function sets a table indicator in the first byte of the user data 
storage area. Any session management exit function routines subsequently invoked 
by VTAM use this table indicator. !f the table indicator is set to hex FF, the function 
routine does not allow a cross-network session to be established. The routine exits 
with the proper return code. 


The begin function also obtains another user data storage area for use by the 
session management exit alias translation function. This storage is initialized and 
maintained by the session management exit routine. The begin function performs a 
GETMAIN request to obtain 4096 bytes of virtual storage for an alias name pool and 
saves the address of the storage in the user data storage area. For more informa- 
tion concerning how this table is used, refer to “Alias Selection Function for MVS 
and VM” on page 130. 


The following sample code obtains the user data storage, loads a NETID registration 
table, and sets the bits appropriately in the exit options field. 


RAKE EERRERREEKEEEKEEKEEEEEEREEEEKERKREKREEKREEEKEEREEERKE 


- SME ROUTINE - BEGIN FUNCTION 


KEKKEKKEKEEEKEKEEKKEKEEEKERKKEKEREKERKEKEEKEKEKEEREKEKKEKEEKEKEEEKEEKERKREKER 


BEGIN EQU  * 
* 


** TSSUE GETMAIN TO OBTAIN USER DATA STORAGE AREA 


* 


BEGINS! €QU * 


GETMAIN R,LV=48 OBTAIN USER DATA STORAGE AREA 
LTR = R15,R15 DETERMINE IF GETMAIN SUCCESSFUL 
BZ BEGINSIA YES, CONTINUE PROCESSING 

B ABEND TERMINATE SME ROUTINE 


* 


** SAVE ADDRESS OF USER DATA STORAGE IN USER DATA FIELD 


* 


BEGINSIA EQU  * 


L R2,8(R11) PARAMETER LIST — USER DATA FIELD ADDRESS 
ST R1,0(R2) SAVE USER DATA STORAGE — GETMAIN 
LR R10,R1 RETAIN ADDRESS OF USER DATA STORAGE 
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XC 0(32,R10),0(R1@) CLEAR USER DATA STORAGE AREA 


* 


** LOAD NETID REGISTRATION TABLE 


* 


BEGINS2 EQU * 


LA R2,BEGINS2A LOAD ERROR CONDITION RETURN ADDRESS 

LOAD EP=NETIDTAB, LOAD MODULE NAME — NETID REGISTRATION TABLE X 
ERRET=(R2) LOAD ERROR RETURN ROUTINE 

B BEGINS2B NO, CONTINUE PROCESSING 


* 


** LOAD FAILURE — SET TABLE INDICATOR 


** 


** NO NETID REGISTRATION TABLE: 


ai X'FF' — INDICATE TO OTHER SME FUNCTIONS DO NOT 


ae PERMIT CROSS NETWORK SESSIONS TO SETUP 

* 

BEGINS2A EQU * 
MVI (R10) ,X‘FF' LOAD FAILURE — SET TABLE INDICATOR 
B BEGINS3 RETURN TO VTAM 


* 


** SAVE LOAD MODULE ADDRESS OF NETID REGISTRATION TABLE IN 
** USER DATA STORAGE AREA AND TEST FOR VALID NETID ENTRIES 
* 


BEGINS2B EQU * 


ST RO,4(R10) SAVE LOAD MODULE ADDRESS — USER DATA STORAGE 
L R2,0(RO) LOAD TABLE ENTRY COUNT 

LTR R2,R2 TEST ENTRY COUNT GREATER THAN ZERO 

BNZ BEGINS3 YES, CONTINUE PROCESSING 


* 


** INVALID NETID REGISTRATION TABLE — SET TABLE INDICATOR 


kk 


** NO VALID NETID ENTRIES: 


ls X'FF' — INDICATE TO OTHER SME FUNCTIONS DO NOT 
= PERMIT CROSS NETWORK SESSIONS TO SETUP 


BEGINZC EQU * 
MVI O(R10),X'FF' INVALID NETID TABLE - SET TABLE INDICATOR 


* 


** OBTAIN STORAGE FOR ALIAS NAME POOL 
* 


BEGINS3 EQU * 


GETMAIN R,LV=4096 OBTAIN ALIAS NAME POOL STORAGE 

LTR R15,R15 DETERMINE IF GETMAIN SUCCESSFUL 
BZ BEGIN3A YES, CONTINUE PROCESSING 

MVI 32(R10) ,X'FF' NO ALIAS NAME POOL - SET INDICATOR 
B BEGINS4 YES, CONTINUE PROCESSING 


* 


** SAVE ADDRESS OF USER DATA STORAGE IN USER DATA FIELD 
* 
BEGINSSA EQU  * 
ST R1,32(R10) SAVE ALIAS NAME POOL STORAGE ADDRESS 
LA RO, 16 INITIALIZE COUNTER TO CLEAR STORAGE 
BEGINS3B EQU * 
XC 0(32,R1) ,O(R1) CLEAR ALIAS NAME POOL STORAGE 
LA R1,256(R1) INCREMENT ADDRESS TO NEXT 256 STORAGE BYTES 
BCT RO,BEGINS3B CONTINUE PROCESSING ALL STORAGE 
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** SET SME EXIT OPTIONS FOR SUBSEQUENT SME FUNCTIONS 


* 


BEGINS4 EQU * 


L R2,12(Ri1) PARAMETER LIST - EXIT OPTIONS ADDRESS 
01 O(R2) ,X'40! SME OPTION - SECONDARY AUTHORIZATION 
0! O(R2) ,X'10' SME OPTION - GATEWAY PATH SELECTION 
0! 1(R2) ,X'20' SME OPTION - ALIAS NAME TRANSLATION 
OI Q(R2) ,X'08' SME OPTION - END FUNCTION 

B RETURN RETURN TO VTAM 


REKKHKKHKEKEEKEKKEKE KA TREKKA EKKEREREKRKEKEERKKKKKKKRKKKKRKEKE 


Returning to VTAM 


Upon completion of these tasks, the begin function returns to VTAM. It is not exe- 
cuted again until VTAM is reinitialized. The code that performs the return to VITAM 
must free the storage used as the register save area for the session management 
exit routine, reestablish the registers for VTAM, and ensure the return is properly 
set. All function routines can use the following code to exit to VITAM. 
KEKE ARE KERR EKERRRCEEAEERKEKKE KKK 

* 


** RETURN TO VTAM 


* 


RETURN EQU * 


L R2,4(R13) RELOAD VTAM'S REGISTER SAVE AREA ADDRESS 

ST R15,16(R2) SET SME FUNCTION RETURN CODE IN VTAM'S REGISTER 15 
FREEMAIN R,LV=72,A=(R13) FREE REGISTER SAVE AREA STORAGE 

LR R13,R2 RESET REGISTER 13 TO VTAM'S SAVE AREA ADDRESS 

LM R14,R12,12(R13) RESTORE VTAM'S REGISTERS 

BR R14 EXIT TO VTAM 


KKKKEKKEKEEERERERERERKEKREEREKREREEEEKEREREKEREREEEKERKEEREEEKEREEEEKKEEK 


Secondary Authorization Function 


Since the session management exit routine does not use the initial authorization 
function, all LU sessions are authorized by the secondary authorization function. 
This sample session management exit routine function examines the NETID of the 
secondary and primary logical units (SLU and PLU). 


lf the NETID associated with both LUs is the same as the host’s (GWVTAM), which is 
passed to the routine in the environment vectors, the session setup is allowed to 
continue. However, if the NETID of either the SLU or the PLU differs from the host’s 
NETID, then the NETID registration table is examined. 


If the table indicator in the first byte of the user data storage area is set to hex FF, 
the cross-network session setup is rejected. if the table indicator is not set to that 
value, the NETID of the appropriate LU is compared to the entries in the NETID reg- 
istration table to determine if the request is valid. If the NETID is not contained in 
the table, the session request is rejected. 


The secondary authorization function parameter list contains the addresses of the 
PLU and the SLU resource identification control vectors (RICs). These RICs contain 
the network identifier associated with both the real and alias LU names. 

Using the sample network environment shown in Figure 12 on page 114, assume 
there is a cross-network session request from a termina! (NO2L0256) in NET1 for a 
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destination logical unit (ASOCICS) in NET2. A sample portion of the PLU RIC that is 
passed to the session management exit routine in the gateway VTAM (G10VTAM) for 
this terminal-initiated session is shown in Figure 15 on page 122. 


DEC (HEX) 
Offset 
@ (80) 
1 (01) 
2 (02) 
3 (03) 
4 (04) 
5 (05) 
12 (0C) 
13 (QD) 
17 (11) 
18 (12) 
25 (19) 
26 (1A) 
30 (1E) 
31 (1F) 


32 (20) 


Figure 15. Sample Portion of PLU Resource Identification Control Vector 


RICs contain more information related to the LU session request than is used by the 
sample session management exit routine. For example, the PLU and SLU RICs 
contain the real and alias names of the LU session partners. The session manage- 
ment exit routine can be expanded to authorize session setup based on the LU 
name of the DLU or OLU partner. The session management exit routine might 
analyze a specific naming convention associated with the LUs, or the NETID regis- 
tration table might be expanded to include LU name registration, depending upon 
the security requirements of the network or application session partners. 
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After it receives the RIC, the session management exit routine must locate the 
NETID of the gateway VTAM host. This information is the first entry following the 
vector list header. 


KRREKKEKEEKKEKEREEKEEKEEREEKKEEREEKKEREEEEEEREREREKEEKEEERREREKREREREEEEEKESE 


= SME ROUTINE - SECONDARY AUTHORIZATION FUNCTION 


REKAKEKEREKEEKEKREKEKAREEREREEEERREEREREKKEKERREEKEKEEEREEEREKKKERERKKKEEK 


SECAUTH EQU * 


L R2,0(R11) ADDRESS OF ENVIRONMENT VECTORS 

CLI 3(R2),X'06' ENSURE HOST NETID VECTOR 

BNE ABEND TERMINATE - NO NETID CONTROL VECTOR 

IC R3,2(R2) LENGTH OF HOST NETID 

LTR R3,R3 ENSURE HOST NETID AVAILABLE 

BZ ABEND TERMINATE - NO HOST NETID START OPTION 
LA R2,4(R2) ADDRESS OF HOST NETID 


KEEKEKERKKEKEEEKEEERKEECEEREERERREKKEREEEKEEEREREEEEEKEEEREKEKEKEKKEEKKERKKER 


The next task is to examine the network identifiers that are passed for the PLU and 
SLU in the RICs. There are two NETIDs in each RIC, one associated with the rea! 
name and the other with the alias name of the LU. 


In this sample, the only network identifier that is important is the reat NETID for 
each LU. The real NETID in each RIC must be examined to determine the direction 
of session setup. The direction of session setup is determined by which LU initiates 
the session, or the mechanism used to initiate the session (terminal-initiated logon, 
automatic logon, or third party logon), or both the LU and mechanism used. 


The usage indicator (byte 4, bit 1) in the RIC identifies whether the resource, either 
PLU or SLU, is the target. Therefore, this indicator can be checked to determine 
whether the RIC for the PLU is the DLU or the OLU. The same task can be per- 
formed for the SLU by examining the indicator in the RIC. 


The following sample code is used to examine the real NETID in the RICs for the 
primary and secondary LUs. The NETID in the RIC for the PLU is first compared to 
the host NETID. If both are the same, the real NETID in the RIC for the SLU must be 
examined. If the PLU and host NETIDs are not the same, the real NETID for the PLU 
is compared to the entries in the NETID registration table. If there is no match, the 
session request is considered to be from an invalid network and the session is 
rejected. 


Note: In the sample, an execute (EX) instruction is used to compare the NETIDs and 
the PLU or the SLU names because the name length in the RIC appears to be vari- 
able. VTAM, however, always uses 8-character names that are padded with blanks. 
Therefore, you are not required to use the EX instruction. You can use a compare 
(CLC) instruction with a length of eight to perform this task. 
HREARKKKKKKEKEREKEEKKEEEEREEEEEAEKEERKREKKERERREKKEKKKKKRR RAK KKK EK 

* 


** LOCATE PLU RESOURCE INFORMATION CONTROL VECTOR — REAL NETID 


* 


SECAUS] EQU * 


LA R15,0 RETURN CODE — ASSUME ACCEPT SESSION REQUEST 
L R4,12(R11) PLU RIC ADDRESS 

LA R4,4(R4) PLU RIC SSCPNAME ADDRESS 

IC R5,0(R4) PLU RIC SSCPNAME LENGTH 

AR R4,R5 PLU RIC REAL NETID ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) PLU RIC NETID LENGTH ADDRESS 

IC R5,0(R4) PLU RIC NETIO LENGTH 

LTR R5,R5 PLU RIC TEST NETID FOR ZERO LENGTH 
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BZ ABEND PLU RIC NETID LENGTH INCORRECT 
BCTR R5,0 PLU RIC NETID LENGTH MINUS ONE 
LA R4,1(R4) PLU RIC NETID ADDRESS 


* 


** COMPARE THE PLU RIC NETID TO HOST NETID IN THE ENVIRONMENT VECTOR 

** IF PLU RIC NETID EQUALS HOST NETID THEN PROCESS SLU RIC NETID 

** ELSE EXAMINE NETID REGISTRATION TABLE FOR VALID NETWORK IDENTIFIER 

* 
EX R5 ,NETID COMPARE PLU RIC REAL NETID TO HOST NETID 
BNE SECAUS3 PLU NETID NOT EQUAL GATEWAY VTAM 


* 


** LOCATE SLU RESOURCE INFORMATION CONTROL VECTOR — REAL NETID 


* 


SECAUS2 EQU * 


L R4,16(R11) SLU RIC ADDRESS 

LA R4,4(R4) SLU RIC SSCPNAME ADDRESS 

Ic R5,0(R4) SLU RIC SSCPNAME LENGTH 

AR R4,R5 SLU RIC REAL NETID ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) SLU RIC NETID LENGTH ADDRESS 

IC R5,0(R5) SLU RIC NETID LENGTH 

LTR R5,R5 SLU RIC TEST NETID FOR ZERO LENGTH 

BZ ABEND SLU RIC NETID LENGTH INCORRECT 

BCTR R5,0 SLU RIC NETID LENGTH MINUS ONE 

LA R4,1(R4) SLU RIC NETID ADDRESS 


* 


** COMPARE THE SLU RIC NETID TO HOST NETID IN THE ENVIRONMENT VECTOR 
** IF SLU RIC NETID EQUALS HOST NETID THEN MUST BE SAME NETWORK SESSION 
** ELSE EXAMINE NETID REGISTRATION TABLE FOR VALID NETWORK IDENTIFIER 
* 
EX R5,NETID COMPARE PLU RIC REAL NETID TO HOST NETID 
BE RETURN SLU NETID EQUALS GATEWAY VTAM — SAME NETWORK 


* 


** EXAMINE NETID REGISTRATION TABLE FOR VALID NETWORK IDENTIFIER 
* 


SECAUS3 EQU * 


L R2,8(R11) USER DATA FIELD ADDRESS 

L R2 ,0(R2) USER DATA STORAGE AREA ADDRESS 
L R2,4(R2) NETID REGISTRATION TABLE ADDRESS 
L R3,0(R2) NETID TABLE ENTRY COUNT 

L R2,4(R2) NETID TABLE ENTRY ADDRESS 


* 


** COMPARE THE PLU OR SLU RIC REAL NETID TO NETID REGISTRATION TABLE ENTRY 
* 


SECAUS3A EQU * 


EX R5,NETID COMPARE PLU/SLU RIC NETID TO TABLE ENTRY 

BE RETURN ACCEPT SESSION REQUEST - VALID NETID ENTRY 
SECAUS3B EQU  * 

LA R2,8(R2) NEXT NETID TABLE ENTRY ADDRESS 

BCT R3,SECAUS3A NETID TABLE ENTRY COUNT NOT ZERO - CONTINUE SEARCH 


* 


** END NETID REGISTRATION TABLE SEARCH — NO VALID ENTRY 
** RETURN CODE — REJECT CROSS NETWORK SESSION REQUEST 
* 
SECAUS3C EQU  * 
LA —-R15,8 NO ENTRY IN NETID REGISTRATION TABLE 
B RETURN EXIT TO VTAM 
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** INSTRUCTION EXECUTED TO COMPARE: PLU RIC REAL NETID TO HOST NETID 


= PLU RIC REAL NETID TO NETID REGISTRATION TABLE 
ae SLU RIC REAL NETID TO HOST NETID 

os SLU RIC REAL NETID TO NETID REGISTRATION TABLE 
* 

NETID CLC 0(0,R4) ,0(R2) NETID COMPARE INSTRUCTION 

* 


REKKKKKEEEKEKKKEEKKEKEREREREEEEEEEKKEKEREKEREEKEEREEEREEEREEKKEKKREREEEKEE 


Gateway Path Selection Function for MVS and VM 


The gateway path selection function can be used when a SNA network intercon- 
nection environment uses multiple gateway NCPs. The gateway VTAM always 
attempts to establish a cross-network session using the same gateway NCP over 
which the CDRM-CDRM session is established. The session management exit 
routine can modify this default gateway path selection. The gateway path selection 
function can either reorder the list of available gateway NCPs or delete entries from 
the fist. 


Each entry in the list is associated with a GWPATH definition statement coded fol- 
lowing a CDRM definition statement. For example, assume the following CDRM and 
GWPATH definition statements are coded in the gateway VTAM (G10VTAM) in NET2: 


VTAMO1  CDRM 
GWNCP30 GWPATH SUBAREA=30,ADJNET=NET1, ADJNETSA=1 , ADJNETEL=1 
GWNCP4Q GWPATH SUBAREA=40, ADJNET=NET1, ADJNETSA=1,ADJNETEL=1 


Assuming that both gateway NCPs (GWNCP30 and GWNCP40) are operative and all 
of the links are active, the first gateway NCP establishes the SSCP-SSCP session 
between the gateway VTAM (G10VTAM) and the VTAM host (VTAM01) in NET1. 


The list of GWPATH definition statements passed to the session management exit 
routine is in the order in which they are coded. The gateway NCP that establishes 
the SSCP-SSCP session, however, is always placed first in the list. Therefore, in the 
example above, if GWNCP30 was not initially available for the SSCP-SSCP session, 
but was operative later, the order of the GWPATH entries is reversed in the list. 


Even though the gateway NCP is operative, links between the gateway NCP and the 
adjacent subarea may not be operative. As a result, a specific gateway NCP is 
selected to setup an LU session; however, the route from gateway NCP to the desti- 
nation subarea is not available. 


If the VTAM in NET1 (VTAM01) is gateway capable only, the gateway path selection 
function is invoked with the list of gateway paths as described above. However, if 
VTAMO1 is a gateway SSCP, and a gateway path selection function in that VIAM 
orders the list of gateway paths, then the entire list of gateway paths is not passed 
to the session management exit in GIOVTAM. Only the first entry in the list that was 
selected by the VTAM0O1 and passed in the CDINIT is supplied to the gateway path 
selection function in GIOVTAM. 
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Examining LU Names 


In the sample network, assume that GWNCP40 is selected for the session between 
the terminal (NO2L0256) and the application (ASOCICS). Route activation for this 
session does not take place until the BIND for the session flows. In this case, the 
BIND flows from the VTAM host (V50CDRM) to the gateway NCP (GWNCP40). 
Assume that the link is not operative between the gateway NCP (GWNCP40) and the 
NCP subarea (NCP02) in NET1. As a result, the virtual route (VR) cannot be acti- 
vated and the LU-LU session fails. There is no information provided to the session 
management exit routine indicating that the route is unavailable, even though the 
gateway NCP is available. If the end user at the terminal attempts to re-initiate the 
session, the session management exit routine, using the same logic, continues to 
select the same gateway NCP over which the complete network route is unavailable. 
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In the sample portion of the session management exit routine, the gateway path 
selection function performs the following logic to select a GWPATH from the list: 


1. 


Examines the real LU name of the application program in the PLU and the SLU 
RIC to determine if the LU name is either ASOCICS or AGOCICS. If the DLU or 
OLU is neither of these names, the session management exit code uses the 


default gateway path selection. 


lf the real LU name is A50CICS, ensures that GWNCP30 is the first entry in the 
list. If the LU name is A60CICS, reorders the list, if necessary, to ensure that 
GWNCP40 is the first entry in the GWPATH selection list 


The following code locates the real LU name for the PLU or SLU. If the LU name is 
not a CICS application, control is returned to VTAM without modifying the GWPATH 


list. 


KKAKAKAKKEKAEKERKEEKEEEEKCEREREEEREEREEEEKEKEEEEARERRERERREKERERERKEREKRREK 


SME ROUTINE - GATEWAY PATH SELECTION FUNCTION 


KEKRKREKEKEEKEEERRKEKREREEKEREEEEEREEKEREREHEREEKEEKRERREREREREREEREEEEKKRKEE 


GWPATH  EQU 


* 


* 


* 


** LOCATE USER DATA STORAGE AREA - GWPATH NAME AND SUBAREA ADDRESS 


* 


GWPTHSIA EQU 


* 


L 
L 


* 


R1,8(R11) 


R1,0(R1) 


USER DATA FIELD ADDRESS 
USER DATA STORAGE AREA ADDRESS 


** LOCATE PLU RESOURCE INFORMATION CONTROL VECTOR — REAL LUNAME 


* 


GWPTHS1B EQU 
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* 


R4,12 (R11) 


R4,4(R4) 
R5,0(R4) 
R4,R5 

R4,1(R4) 
R5,0(R4) 


RA. 1(R4) 


PLU RIC ADDRESS 

PLU RIC SSCPNAME ADDRESS 

PLU RIC SSCPNAME LENGTH 

PLU RIC REAL NETID ADDRESS VECTOR MINUS ONE 
PLU RIC NETID LENGTH ADDRESS 

PLU RIC NETIO LENGTH 

PLU RIC REAL LUNAME ADDRESS VECTOR MINUS ONE 
PLU RIC REAL LUNAME LENGTH ADDRESS 

PLU RIC REAL LUNAME LENGTH 

PLU RIC REAL LUNAME LENGTH MINUS ONE 

PLU RIC REAL LUNAME ADDRESS 
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** COMPARE THE PLU RIC LUNAME TO APPLICATION NAME: ASOCICS OR AGOCICS 


* 


EX R5,CICS5O COMPARE PLU RIC REAL LUNAME TO ACICS50 
BE GWPTHS2A YES, REORDER GWPATH AS NECESSARY 
EX R5,CICS60 COMPARE PLU RIC REAL LUNAME TO ACICS60 
BE GWPTHS2B YES, REORDER GWPATH AS NECESSARY 


* 


** LOCATE SLU RESOURCE INFORMATION CONTROL VECTOR - REAL LUNAME 
* 


GWPTHSIC EQU * 
L 


R4,16(R11) SLU RIC ADDRESS 
LA R4,4(R4) SLU RIC SSCPNAME ADDRESS 
IC R5,0(R4) SLU RIC SSCPNAME LENGTH 
AR R4,R5 SLU RIC REAL NETID ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) SLU RIC NETID LENGTH ADDRESS 
Ic R5,0(R5) SLU RIC NETID LENGTH 
AR R4,R5 SLU RIC REAL LUNAME ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) SLU RIC REAL LUNAME LENGTH ADDRESS 
IC R5,0(R4) SLU RIC REAL LUNAME LENGTH 
BCTR R5,0 SLU RIC REAL LUNAME LENGTH MINUS ONE 
LA R4,1(R4) SLU RIC REAL LUNAME ADDRESS 


+ 


* COMPARE THE SLU RIC LUNAME TO APPLICATION NAME: A5OCICS OR A6OCICS 


EX R5,CICS5O COMPARE PLU RIC REAL LUNAME TO ACICS50 
BE GWPTHS2A YES, REORDER GWPATH AS NECESSARY 
EX R5,C1ICS60 COMPARE PLU RIC REAL LUNAME TO ACICS60 
BE GWPTHS2B YES, REORDER GWPATH AS NECESSARY 


** TF NEITHER THE PLU OR SLU RIC REAL LUNAME EQUALS A50CICS OR A6OCICS 
** THEN SET RETURN CODE TO PROCEED WITH DEFAULT GWPATH SELECTION LIST 


LA R15,4 RETURN CODE TO USE DEFAULT GWPATH LIST 
B RETURN RETURN CONTROL TO VIAM 


** PLU OR SLU RIC REAL LUNAME EQUALS ASOCICS - 
* SAVE FIRST GWPATH ENTRY NAME AND SUBAREA ADDRESS IN USER DATA STORAGE 


* 


* 


GWPTHS2A EQU * : 
MVC 8(8,R1) ,GWNCP30 FIRST GWPATH NAME MUST BE GWNCP30 


LA R5,30 FIRST GWPATH SUBAREA MUST BE 30 
ST R5,16(R1) SAVE IN USER DATA STORAGE 
B GWPTHS3 CONTINUE, REORDER GWPATH LIST IF NECESSARY 


* 


** PLU OR SLU RIC REAL LUNAME EQUALS AGOCICS - 
** INITIALIZE REGISTERS TO MODIFY GWPATH SELECTION LIST AS NECESSARY 
* 
GNPTHS2B EQU * 
MVC 8(8,R1),GWNCP40 FIRST GWPATH NAME MUST BE GWNCP40 


LA R5,40 FIRST GWPATH SUBAREA MUST BE 40 
ST R5,16(R1) SAVE IN USER DATA STORAGE 
B GWPTHS3 CONTINUE, REORDER GWPATH LIST IF NECESSARY 
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** INSTRUCTIONS EXECUTED TO COMPARE: PLU RIC REAL LUNAME TO AS5QCICS OR A6OCICS 
=. SLU RIC REAL LUNAME TO A5@CICS OR AGOCICS 
* 

CICS50 CLC 0(0,R4),C'ASOCICS' LUNAME COMPARE INSTRUCTION 

CICS60 CLC 0(0,R4),C'AGOCICS' LUNAME COMPARE INSTRUCTION 

* 


** CONSTANTS - GATEWAY NCP NAMES OCICS 
* 

GWNCP30 DC CL8'GWNCP30' GATEWAY NCP NAME - GWNCP30 

GWNCP490 DC CL8' GWNCP40' GATEWAY NCP NAME - GWNCP40 

* 


RHRAEKEKKRKEEKRKEKEKREKREKREKEERRERERERERKKRKKEEREREEREKEKRERREREREREREKREKEKERKEEKRE 


Modifying Gateway Path Selection List 


After the session management exit routine determines that the real LU name is 
associated with CICS, the gateway path selection function reorders the gateway 
path selection list as appropriate. If the application program name is A50CICS, the 
first entry in the Jist must be GWNCP30. Conversely, if the LU name is A60CICS, the 
first GWPATH entry must be GWNCP40. The above sample code locates the LU 
name in the RIC and, if the proper CICS name is determined, branches to the 
sample code below. In this case, the user data storage area is initialized with the 
gateway NCP name and the corresponding subarea address of the first entry in the 
list. 


The session management exit routine must next locate the GWPATH selection list. 
Since only one gateway NCP may be available, the gateway path function must 
determine if the list contains more than one entry. If there is only one entry in the 
list, the exit routine returns to VTAM and uses the default list. However, if there is 
more than one entry in the gateway selection list, the code must read the first entry 
and reorder the list, if necessary. 


The gateway path selection list is reordered by moving the first entry name and 
subarea address into user data storage and moving the preferred gateway NCP 
name and subarea address to the first entry in the list. The entry which was previ- 
ously the first entry in the list must then be moved from user data storage back into 
the gateway path list to complete the swap. 


If the gateway path NCP name (GWN) is blank, the preferred gateway NCP is inac- 
tive. In that case, the first entry in the selection list must be reset to the original 
name and subarea address. 


Note: In the sample, the GWN is checked to determine if the preferred gateway 
NCP is inactive because the SUBAREA operand was used on the GWPATH definition 
statement. If you use the GWN operand instead of the SUBAREA operand, the 
subarea address is set to zero, indicating that the preferred gateway path is inac- 
tive. If both operands are coded, there is no means of determining if that gateway is 
inactive. 


The following sample session management exit code performs these tasks. 


Figure 16 on page 129 also illustrates the contents of the entries in the gateway 
path selection list for the sample network environment. 
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DEC (HEX) 
Offset 


0 (6) nn (TOTAL LENGTH) 
2 (2) 
10 (A) 
12 (C) 
13 (D) 
21 (15) 
25 (19) 
33 (21) 
34 (22) 


21 (15) 


25 (19) NET1 (with 4 blanks) 


Figure 16. Gateway Path Selection List for Sample Session Management Exit Routine 


REKEEKKKKEEEKKEKEKEEREKEEEKEEREKRKKEKEEKEEKEEREREKKEKKEEEKEKERKEREKEKKREK 


GWPTHS3 EQU * 


LA R15,4 RETURN CODE ASSUMES DEFAULT GWPATH LIST 
L R2,28(R11) GATEWAY PATH SELECTION LIST ADDRESS 

LH R3, 10(R2) OBTAIN THE NUMBER OF GWPATH ENTRIES 

LA R2,12(R2) FIRST GWPATH ENTRY ADDRESS 

LA R4,1 INITIALIZE REGISTER WITH VALUE OF ONE (1) 
CR R3,R4 GWPATH ENTRIES GREATER THAN ONE 

BH GWPTHS3A YES, LOCATE NAME OF FIRST GWPATH ENTRY 

B RETURN RETURN CONTROL TO VTAM 


* 


** EXAMINE FIRST GWPATH SUBAREA ADDRESS (SUBAREA OPERAND) 

kk 

** COMPARE SUBAREA ADDRESS ENTRY TO PREFERRED ADDRESS IN USER DATA STORAGE 
** TF BOTH ENTRIES EQUAL RETURN TO VTAM AND USE DEFAULT SELECTION LIST 


GWPTHS3A EQU  * 
CLC 9(4,R2),16(R1) | FIRST GWNCP SAME AS PREFERRED GWPATH 
BE RETURN PREFERRED GWNCP FIRST, USE DEFAULT LIST 

* 

** FIRST GWPATH ENTRY NOT EQUAL TO PREFERRED GWPATH 

** SAVE CURRENT FIRST ENTRY IN SELECTION LIST IN USER DATA STORAGE 

** SWAP PREFERRED ENTRY WITH FIRST ENTRY IN SELECTION LIST 

* 

GWPTHS3B EQU  * 
MVC 20(8,R1),1(R2) SAVE GWNAME IN USER DATA STORAGE 
MVC 28(4,R1),9(R2) | SAVE SUBAREA ADDRESS IN USER DATA 

* STORAGE 
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MVC =1(8,R2) ,8(R1) SWAP PREFERRED GWNAME FROM USER DATA 
. STORAGE 

MVC 9(4,R2),16(R1) SWAP PREFERRED SUBAREA ADDRESS FROM 
. USER DATA STORAGE 


** LOCATE PREFERRED GWPATH ENTRY IN SELECTION LIST TO COMPLETE SWAP 

kk 

** COMPARE THE NEXT SUBAREA ADDRESS ENTRY IN THE GWPATH SELECTION LIST 

** TO THE PREFERRED ENTRY IN USER DATA STORAGE. IF EQUAL, ENSURE THE 

** PREFERRED GWPATH IS NOT INACTIVE. COMPARE THE GWNCP NAME TO BLANKS. 

** IF ACTIVE, COMPLETE THE GWPATH SWAP, OTHERWISE RESET THE FIRST ENTRY 
** TO THE ORIGINAL CONDITION. 


* 


GWPTHS3C EQU  * 


Ic R4,0({R2) OBTAIN GWPATH ENTRY LENGTH 
AR R2,R4 NEXT GWPATH ENTRY ADDRESS 
CLC 9(4,R2),16(R1) GWPATH SUBAREA ADDRESS USED AS FIRST 
. ENTRY 
BNE GWPTHS3D NO, EXAMINE NEXT ENTRY 
CLC 1(8,R2),XL8'40' CHECK IF GWPATH NAME BLANK 
BE GWPTHS3E PREFERRED GWNCP NOT ACTIVE, RESET 
. FIRST ENTRY 
MVC ©1(8,R2) ,20(R1) SWAP FIRST ENTRY GWNAME FROM USER 
is DATA STORAGE 
MVC = =©9(4,R2) ,28(R1) SWAP FIRST ENTRY SUBAREA ADDRESS 
= FROM USER DATA STORAGE 
LA R15,0 RETURN CODE, USE MODIFIED GWPATH LIST 
B RETURN RETURN CONTROL TO VTAM 


** EXAMINE NEXT ENTRY IN GWPATH SELECTION LIST 


** IF LIST EXHAUSTED AND PREFERRED GWPATH ENTRY NOT LOCATED THEN 
** SWAP FIRST ENTRY BACK TO ORIGINAL GWPATH BECAUSE THE PREFERRED 
** GWPATH ENTRY IS NOT AVAILABLE IN THE LIST. 


* 


GWPTHS3D EQU * 


BCT R3,GWPTH3C LAST GWPATH ENTRY, NO CONTINUE PROCESS 
GWPTHS3E EQU * 

L R2,28(R11) GATEWAY PATH SELECTION LIST ADDRESS 

LA R2,12(R2) FIRST GWPATH ENTRY ADDRESS 

MVC 1(8,R2) ,20(R1) SWAP FIRST ENTRY GWNAME FROM USER 
* DATA STORAGE 

MVC 9(4,R2) ,28(R1) SWAP FIRST ENTRY SUBAREA ADDRESS 
: FROM USER DATA STORAGE 

B RETURN USE ORIGINAL DEFAULT GWPATH LIST 


RRR EERE EEEREEEEEREEEREEREREREEREREEEKE 


Alias Selection Function for MVS and VM 


The alias selection function of the session management exit routine performs 
various name translation tasks. VTAM maintains both a real and an alias network- 
qualified name for each LU session partner. VTAM can invoke this function to deter- 
mine any one of the following four names: 


e Real network-qualified name for the PLU or DLU 
e Alias network-qualified name for the PLU or DLU 
e Real network-qualified name for the SLU or OLU 
¢ Alias network-qualified name for the SLU or OLU. 
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in addition, the alias selection function can map a class-of-service (COS) name for 
one network to the COS name used in another network. It can also map logon mode 
entry names or supply the SSCP owner for a particular resource name. 


In this sample, the alias function translates the real LU name of a terminal in NET1 
into an alias name in NET2. The primary applications (CICS and IMS) in NET2 
require the terminal names to be generated in these subsystems. All terminals in 
NET1 that require access to these applications must be generated into the subsys- 
tems. Since the subsystem maintenance and coordination associated with a large 
quantity of other-network terminals can be difficult, the alias function translates a 
real terminal name into an alias terminal name. 


The alias terminal name is selected from a preassigned pool of alias names. This 
pool can be pre-generated into the IMS and CICS applications. When all the names 
in the pool are allocated to concurrent cross-network sessions, subsequent session 
requests fail. Once a name is freed as a result of a session termination, another 
cross-network session can be established. Therefore, the preassigned alias name 
pool needs to contain sufficient entries to accommodate the peak concurrent cross- 
network session count for CICS and !MS. 


The session management exit routine must first examine the indicators associated 
with the LU names to determine what translation is necessary. For example, 
assume there is a terminal-initiated session from NO2L0256 for the application 
program A7OIMS in NET2. There are four network qualified names associated with 
this session request, as shown in Figure 17. 


Origin Destination 
Logical Unit Logical Unit 


NET1.NO2L0256 NET2.A70IMS 
} Alias Name | NET2.ALTASnnn NET1.A701MS 


Where nnn is the suffix added to the alias terminal name 
allocated from the alias name pool for terminals in NET1. 


Alias Name 


Figure 17. Real and Alias Network-Qualified Names 


Translating DLU Name 
For a terminal-initiated session using CDINIT processing (or DSRLST), the first entry 
in the alias input parameter list is the DLU, A70IMS. The alias function examines 
the OLU/DLU status indicator and the DLU name that requires translation. !f the 
DLU name is a NET2 application program (IMS or CICS), the same LU name is used 
for the real LU name and only the NETID of NET2 needs to be supplied. 


The session management exit routine initializes the output fields to a value of 
A7OIMS for the LU name (RTNNAME1) and NET2 for the NETID (RTNNET1). 
However, if the first entry is not the DLU, or the LU name is not one of the NET2 
application programs, the direction of session setup does not permit the alias func- 
tion to provide an alias name; that is, a session initiated from the CICS or IMS appli- 
cation requires the real name of the terminal. This sample session management 
exit routine cannot map an alias terminal that is pre-generated in IMS or CICS into a 
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specific terminal name in the attached network (NET1). Therefore, this sample 
session management exit routine returns control to VTAM and indicates that no 
translation is performed. The session setup proceeds assuming the correct names 
are supplied. The following sample code processes the first entry in the alias input 
parameter list: 


KEREKKKEREKREEKEREEKEKEERERKEEEREEKREREREREREKEEEEKEKREREREREKEEEREREKEREE 


. SME ROUTINE - ALIAS SELECTION 

FRI RIOR RII III I RII II ATI IIIA IIIS IIIS II IASI IISA SAIS AS SSS ISIN ANI II 
ALIAS EQU  * 

* 

** LOCATE THE ALIAS PARAMETER LIST - INPUT AND OUTPUT ADDRESSES 

* 


ALIASS] €QU = * 


L R2,44(R11) ALIAS INPUT PARAMETER LIST ADDRESS 
LA R2 ,8(R2) ALIAS FIRST LUNAME ADDRESS - REAL/ALIAS NAME 
L R3,48(R11) ALIAS OUTPUT PARAMETER LIST ADDRESS 


* 


** PROCESS FIRST LOGICAL UNIT NAME IN ALIAS INPUT PARAMETER LIST: 

** 

** TF FIRST ENTRY IS THE DLU AND NAME IS 'AS5OCICS', 'A6OCICS', OR ‘A7OIMS' 
** RETURN SAME NAME TO VTAM AND CHANGE THE NETID TO 'NET2', OTHERWISE, 

** EXIT TO VTAM WITHOUT ALIAS TRANSLATION. 


** REASONS: 1. TERMINAL INITIATED SESSION TO APPLICATION WHICH DOES NOT 


** REQUIRE ALIAS TRANSLATION. 
ia 2. APPLICATION INITIATED SESSION FOR WHICH SME EXIT CANNOT 
a MAP THE ALIAS NAME TO A REAL TERMINAL NAME 
** 3. CDINIT-OTHER PROCESSING FOR WHICH SME EXIT DOES NOT 
** PROVIDE NECESSARY TRANSLATION. 
* 
ALIASSIA EQU * 
T™ —-1(R2) ,X'20° FIRST ENTRY - DLU NAME FOR CDINIT/DSRLST 
* PROCESSING 
BNO ALIASS1B NO, ALIAS TRANSLATION NOT PERFORMED 
CLC 8(R2),CL8'ASOCICS' ALIAS NAME EQUAL ASOCICS APPLICATION 
BE  ALIASSIC YES, RETURN SAME LUNAME AND NET2 NETID 
CLC 8(R2),CL8'AGOCICS' ALIAS NAME EQUAL A6GCICS APPLICATION 
BE  ALIASS1C YES, RETURN SAME LUNAME AND NET2 NETID 
CLC 8(R2),CL8'A7OIMS' ALIAS NAME EQUAL A7OIMS APPLICATION 
BE  ALIASSIC YES, RETURN SAME LUNAME AND NET2 NETID 
ALIASSIB EQU * 
LA ——-R15,0 NO TRANSLATION PERFORMED - NO ALIAS 
* APPLICATION 
B —_—-RETURN RETURN TO VTAM 
ALIASSIC EQU * 
MVC 0(8,R3) ,8(R2) REAL DLU NAME EQUALS ALIAS APPLICATION NAME 
MVC 48(8,R3) ,CL8'NET2’ REAL NETID FOR DLU EQUALS NET2 
B — ALIASS2 CONTINUE PROCESSING, SECOND ALIAS ENTRY 


REKRKHK KEKE AREER EREREEREREREREEEEKREEEEERKEEEEREEREREREREER 
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Translating OLU Name 


The next step is to translate the OLU name. The indicator for the OLU fields 
(NAME2) specifies that the real name is provided and an alias name must be 
returned. The sample exit routine allocates up to 999 names. The names consist of 
a required prefix, “ALIAS,” and a 3-digit suffix allocated from an alias-suffix table. 
This table is initialized and maintained in a user storage area by the exit routine. 

An alias table can be loaded in the begin function similar to the NETID registration 
table. The sample code below examines the second entry of the alias input parame- 
ters and invokes a subroutine to allocate an alias name from the table. 


Note: For this example you must set the CDRSCTI start option to zero so that the 
alias LU name assigned to the terminal can be deleted and reassigned to another 
reai terminal once the session is terminated. CDRSCTI may have a value other than 
zero for real operations. 


HHH KHER KERR EIRENE EIR REE IARI AES IKE REAR EIT 


ALIASS2 EQU * 
LA R2,32(R2) ALIAS SECOND LUNAME ADDRESS - REAL/ALIAS NAME 


* 


** PROCESS SECOND LOGICAL UNIT NAME IN ALIAS INPUT PARAMETER LIST: 
kk 

** TF SECOND ENTRY IS THE REAL NAME OF THE TERMINAL, THEN 

** ALLOCATE AN ALIAS NAME FROM THE ALIAS NAME POOL, OTHERWISE, 

** EXIT TO VTAM WITHOUT ALIAS TRANSLATION. 


kk 


** REASON: 1. THE TERMINAL IS THE OLU AND THE NAME REQUESTED BY VTAM 


* IS THE REAL NAME FOR THE OLU AND THE SME ROUTINE ONLY 
+ PROVIDES ALIAS NAMES. 
* 
ALIASS2A EQU * 

TH = -2(R2),X'80! SECOND ENTRY - REAL NAME SUPPLIED 

BO _ ALIASS2C YES, PERFORM ALIAS TRANSLATION 
ALIASS2B EQU * 

LA —-R15,8 SOME TRANSLATION PERFORMED - NO ALIAS 
* APPLICATION 

B RETURN RETURN TO VTAM 


ALIASS2C EQU  * 
* 


** IF THE INDICATOR IN THE FIRST BYTE OF THE ALIAS STORAGE ADDRESS IN 
** THE USER DATA STORAGE AREA IS X'FF', THEN STORAGE WAS NOT AVAILABLE 
** FOR THE TABLE. NO ALIAS PROCESSING CAN BE PERFORMED, THEREFORE EXIT. 


** OTHERWISE, BRANCH TO SUBROUTINE THAT ALLOCATES AN AVAILABLE ALIAS NAME 

** SUFFIX FROM THE ALIAS NAME POOL. IF ALL ENTRIES ARE USED, REGISTER 15 (R15) 
** CONTAINS A NON-ZERO RETURN CODE FOR VTAM WHICH DOES NOT ALLOW SESSION 

** INITIATION TO CONTINUE. OTHERWISE, THE ADDRESS FOR THE ALIAS NAME SUFFIX 
** TS ADDRESSABLE AT DISPLACEMENT ONE (1) USING REGISTER 1 (R1). THE SUFFIX 
** TS APPENDED TO THE FIVE CHARACTER STRING 'ALIAS' TO FORM THE ALIAS NAME 

** FOR THE TERMINAL. 


L R4,8(R11) PARAMETER LIST - USER DATA ADDRESS 

L R4,0(R4) USER DATA STORAGE ADDRESS 

CLI 32(R4),X'FF' EXAMINE IF ALIAS NAME STORAGE OBTAINED 

BNE ALIASZ2E YES, CONTINUE ALIAS NAME PROCESSING 
ALIASS2D EQU * 

LA R15,20 NO ALIAS FUNCTION AVAILABLE - FAIL SESSION 
? SETUP 
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B RETURN RETURN TO VTAM - NO ALIAS APPLICATION 
ALIASS2E EQU * 

L R4 ,32(R4) ALIAS NAME STORAGE ADDRESS 

BAL R14,ALIASS3 BRANCH TO ALIAS NAME ALLOCATION ROUTINE 

LTR R15,R15 ALIAS SUFFIX AVAILABLE 

BNZ RETURN RETURN TO VTAM - NO ALIAS ENTRY AVAILABLE 


ALIASS2C EQU * 
MVC 8(5,R3),C'ALIAS' ALIAS OUTPUT PARAMETER - ALIAS NAME PREFIX 
MVC =13(3,R3) ,1(R1) ALIAS OUTPUT PARAMETER - ALIAS NAME SUFFIX 
MVC 56(8,R3),CL8'NET2' ALIAS OUTPUT PARAMETER - ALIAS NETID 
LA R15,8 SOME TRANSLATION PERFORMED - NO COS, LOGMODE 
B RETURN RETURN TO VTAM - NO ALIAS APPLICATION 


REKKEKEEKERKEKKEEEREKEEEKREREKREREEKREKREKEKEREEKEREEERREEEKEREREEKEKRKKKRKS 


The subroutine that processes the alias suffix table initializes the storage, obtained 
in the begin function, during the first pass through the allocation process. During 
the first pass, no entry is allocated as indicated by a hex 00 in the first byte. After 
the entry is allocated, a hex FF :s moved to the first byte in the alias suffix entry. A 
binary counter for the entry number is converted to a 3-byte decimal value, the 
suffix, and is saved in the remaining 3 bytes of the 4-byte entry. The address of the 
alias suffix entry is then returned to the alias function that invoked the subroutine. 
The suffix is appended to the prefix string “ALIAS” to form the alias name. 


The format of the table is illustrated in Figure 18 on page 135. An example of the 
subroutine code that performs the suffix allocation follows Figure 18. 
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DEC (HEX) 
Offset 


0 (0) 


8 (8) 


9 (9) 


12 (C) 


13 (D) 


16 (F) 


17 (11) 


3992 (398) 


3993 (399) 


Figure 18. Alias Terminal Name Pool - Three Digit Suffix 


WORKAREA 


Allocation indicator: 
X'00' - unallocated 
X'FF' - allocated 


Three Digit Suffix 
X'FOFOFO' 


Allocation indicator: 
X'@O' - unallocated 
X'FF' - allocated 


Three Digit Suffix 
X' FOFOF1' 


Allocation indicator: 
X'00' - unallocated 
X'FF' - allocated 


Three Digit Suffix 
X'FOFOF2' 


Allocation indicator: 
X'@O' - unallocated 
X'FF' - allocated 


Three Digit Suffix 
X'FOFOFS9' 


Alias Selection Function 


HRERKAKKRKKKKKEREKTEETEREEKRKEKEKEREKREKTEEEKEEKERKKEREREREKEERERKEKKK KKK 


ALIASS3 EQU 
* 


** ALIAS NAME SUFFIX ALLOCATION SUBROUTINE 


kk 


** Rl = ADDRESS OF ALIAS NAME SUFFIX ENTRY ALLOCATED 


* 


** R4 = ADDRESS OF ALIAS NAME SUFFIX STORAGE - WORKAREA FOR CONVERT TO DECIMAL 


ALIAS SUFFIX ENTRY COUNTER - DECREMENTED 
ALIAS SUFFIX ENTRY COUNTER - CONSTANT 
RETURN ADDRESS - MAIN ROUTINE OF ALIAS FUNCTION 


** RE = 
** RT = 
** R14 = 
** R15 = RETURN CODE 
* 

LA 

LA 

LA 


ALIASS3A EQU 
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CLI O(R1),X‘60' ALIAS SUFFIX ENTRY ALLOCATED 
BNE ALIASS38B YES, INCREMENT ADDRESS TO NEXT ENTRY 
MVI O(R1),X'FF' NO, ALLOCATE ALIAS SUFFIX ENTRY 
SR R7 ,R6 CALCULATE ALIAS SUFFIX ENTRY VALUE - BINARY 
CVD R7,0(R4) CONVERT ALIAS SUFFIX ENTRY TO DECIMAL - 
= WORKAREA 
UNPK 1(3,R1),6(2,R4) UNPACK SUFFIX VALUE INTO PROPER SUFFIX ENTRY 
0! 3(R1) ,X'FO' ENSURE DECIMAL VALUE - CHANGE SIGN OF LAST 
* CHARACTER 
BR R14 RETURN TO INVOKING ROUTINE 
ALIASS3B EQU  * 
LA R1,4(R1) INDEX ALIAS SUFFIX ADDRESS TO NEXT ENTRY 
BCT R6,ALIASS3A DECREMENT ALIAS SUFFIX COUNTER - CONTINUE IF 
= NONZERO 
LA R15,20 ALL ALIAS SUFFIX ENTRIES ALLOCATED - ENTRIES 
" EXHAUSTED 
BR R14 RETURN TO INVOKING ROUTINE - TERMINATE 
3 SESSION SETUP 


REAR KEEEKEKERERUKRREREKEKREKEEKEEEEEEEEEEEREREEEKEEREKEKAK 


Final Accounting Function 


Since the alias selection function is not invoked at session termination, the session 
management exit routine can only allocate the alias suffix entries. Another session 
management exit function must deallocate the alias suffix entry when a session 
ends. The final accounting function, function code hex 03, performs this task. 


The final accounting function examines the alias LU name in the RIC of the PLU and 
the SLU. If the LU name contains a five character prefix of “ALIAS,” the session 
management exit routine can deallocate the proper alias suffix entry. This is done 
by converting the fast three characters of the alias name to a binary value. That 
value is an index into the alias suffix storage area. The code then resets the allo- 
cation indicator from hex FF to hex 00. 
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The entire final accounting function is not included in this sample; however, the 
portion of code that deallocates the appropriate entry at session termination follows: 


RHKKEKKKKKEKKKEKEKEEKEEKEKEEEEKKEKKKEKREEKEEEREEKEEKKEEKEEEKEKRKKKEKKKKKKKRE 


ia SME ROUTINE - FINAL ACCOUNTING FUNCTION - DEALLOCATE ALIAS 
. SUFFIX ROUTINE 
ALTASS4 EQU * 

L R1,8(R11) USER DATA FIELD ADDRESS 

L R1,0(R1) USER DATA STORAGE AREA ADDRESS 

L R1,32(R1) ALIAS SUFFIX STORAGE ADDRESS 

LA R15,0 NO FINAL ACCOUNTING RETURN CODE 

CLI. = 32(R1),X'FF' TEST IF ALIAS SUFFIX STORAGE OBTAINED 

BE RETURN NO, ALTAS TRANSLATION NOT PERFORMED - 
- VTAM RETURN 

L R1,32(R1) ALIAS SUFFIX STORAGE ADDRESS 


* 


** LOCATE PLU RESOURCE INFORMATION CONTROL VECTOR — ALIAS LUNAME 


* 


ALIASS4A EQU * 


L R4,12(R11) PLU RIC ADDRESS 

LA R4,4(R4) PLU RIC SSCPNAME ADDRESS 

IC R5,0(R4) PLU RIC SSCPNAME LENGTH 

AR R4,R5 PLU RIC REAL NETID ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) PLU RIC NETID LENGTH ADDRESS 

IC R5,0(R4) PLU RIC NETID LENGTH 

AR R4,R5 PLU RIC REAL LUNAME ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) PLU RIC REAL LUNAME LENGTH ADDRESS 

IC R5,0(R4) PLU RIC REAL LUNAME LENGTH 

AR R4,R5 PLU RIC ALIAS NETID ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) PLU RIC ALIAS NETID LENGTH ADDRESS 

IC R5,0(R4) PLU RIC ALIAS NETIO LENGTH 

AR R4,R5 PLU RIC ALIAS LUNAME ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) PLU RIC ALIAS LUNAME ADDRESS 

CLC} 0(5,R4),C'ALIAS' PLU RIC ALIAS NAME EQUAL 'ALIAS' 

BE ALIASS4C PLU ALIAS NAME ALLOCATED BY SME - DEALLOCATE 


* 


** LOCATE SLU RESOURCE INFORMATION CONTROL VECTOR —- REAL LUNAME 


* 


ALIASS4B EQU * 


L R4,16(R11) SLU RIC ADDRESS 
LA R4,4(R4) SLU RIC SSCPNAME ADDRESS 
IC R5,0(R4) SLU RIC SSCPNAME LENGTH 
AR R4,R5 SLU RIC REAL NETID ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) SLU RIC NETID LENGTH ADDRESS 
IC R5,0(R5) SLU RIC NETID LENGTH 
AR R4,R5 SLU RIC REAL NETID ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) SLU RIC REAL LUNAME LENGTH ADDRESS 
IC R5,0(R4) SLU RIC REAL LUNAME LENGTH 
AR R4,R5 SLU RIC ALIAS NETID ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) SLU RIC ALIAS NETID LENGTH ADDRESS 
IC R5,0(R4) SLU RIC ALIAS NETID LENGTH 
AR R4,R5 SLU RIC ALIAS LUNAME ADDRESS VECTOR MINUS ONE 
LA R4,1(R4) SLU RIC ALIAS LUNAME ADDRESS 
CLC 0(5,R4),C'ALIAS' SLU RIC ALIAS NAME EQUAL '‘ALIAS' 
BNE RETURN SLU RIC ALIAS NAME NOT ALLOCATED BY SME - 
= VTAM RETURN 
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** ALTAS NAME SUFFIX ALLOCATION SUBROUTINE 


** R1 = ADDRESS OF ALIAS NAME SUFFIX STORAGE 

** R2 = ALIAS SUFFIX ENTRY INDEX 

** R4 = ADDRESS OF ALIAS NAME NAME - PLU/SLU RIC 

** R14 = RETURN ADDRESS - MAIN ROUTINE OF ALIAS FUNCTION 


ALTASS4C EQU  * 
PACK 0(8,R1),5(3,R4) PACK ALIAS SUFFIX VALUE 


CVB R2,0(R1) CONVERT ALIAS SUFFIX ENTRY TO BINARY INDEX 
ig VALUE 

LA R1,8(R2,R1) CALCULATE ALIAS SUFFIX ENTRY ADDRESS 

MVI O(R1),X'60' DEALLOCATE ALIAS SUFFIX ENTRY 

B RETURN EXIT TO VTAM 


HHEKEKKEKKKEREKKRERKEEEKERKRERERERKEREEKEREEKEKERERKREEKKEERKEEREEEEREHKRRER 


End Function 


The end function of the session management exit is invoked during VTAM termi- 
nation. The session management exit routine uses this function to perform any 
cleanup required before VTAM completes termination. In this sample, the begin 
function obtained virtual storage for maintaining user data and loaded a network 
registration table. Therefore, the end function must delete the table and free the 
storage before returning control to VTAM. The following code performs these nec- 
essary functions: 


HEKEKEEKREKKEEKREKEKERKREEREREREEREEEEEKREREEEEEERERREKKEERKEREKEEKEEEREKEEE 


™ SME ROUTINE - END FUNCTION 


KREEKKEREEERKKKKEERRERKEEEEEEKEREEEHEEKREKEEEEKEEEEKEEKEEERKKKKKKAKKKE 


END FQU * 


* 


** DELETE NETID REGISTRATION TABLE 


* 


DELETE EP=NETIDTAB ISSUE DELETE MACRO TO CANCEL PREVIOUS LOAD 


* 


** FREE ALIAS NAME POOL STORAGE 


* 


L R2,8(R11) LOCATE USER DATA FIELD IN PARAMETER LIST 
L R2,0(R2) OBTAIN ADDRESS OF USER DATA STORAGE 

L R3,32(R2) OBTAIN ADDRESS ALIAS NAME POOL STORAGE 
FREEMAIN R,LV=4096,A=(R3) 


* 


** FREE USER DATA STORAGE AREA 
* 
FREEMAIN R,LV=48,A=(R2) 
B RETURN 


KREKKRKEEKREKEKEEEEREEREEKRERREREREEREREREEREEEREEEKEEREERERERRERRERERKREKRKKE 
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Glossary 


This glossary defines important NCP, NetView, 
NetView/PC, SSP, and VTAM abbreviations and terms. 
it includes information from the /BM Dictionary of Com- 
puting, SC20-1699. Definitions from the American 
National Dictionary for Information Processing are 
identified by an asterisk (*). Definitions from draft pro- 
posals and working papers under development by the 
International Standards Organization, Technical Com- 
mittee 97, Subcommittee 1 are identified by the symbol 
(TC97). Definitions from the CCITT Sixth Plenary 
Assembly Orange Book, Terms and Definitions and 
working documents published by the Consultative Com- 
mittee on International Telegraph and Telephone of the 
international Telecommunication Union, Geneva, 1980 
are preceded by the symbol (CCITTATU). Definitions 
from published sections of the /SO Vocabulary of Data 
Processing, developed by the international Standards 
Organization, Technical Committee 97, Subcommittee 1 
and from published sections of the /SO Vocabulary of 
Office Machines, developed by subcommittees of ISO 
Technical Committee 95, are preceded by the symbol 
(iSO). 


For abbreviations, the definition usually consists only of 
the words represented by the letters; for complete defi- 
nitions, see the entries for the words. 


Reference Words Used in the Entries 


The following reference words are used in this 
glossary: 


Deprecated term for. Indicates that the term should 
not be used. It refers to a preferred term, which is 
defined. 


Synonymous with. Appears in the commentary of a 
preferred term and identifies less desirable or less 
specific terms that have the same meaning. 


Synonym for. Appears in the commentary of a less 
desirable or less specific term and identifies the 
preferred term that has the same meaning. 


Contrast with. Refers to a term that has an opposed 
or substantively different meaning. 


See. Refers to multiple-word terms that have the 
same fast word. 


See also. Refers to related terms that have similar 
(but not synonymous) meanings. 


abend. Abnormal end of task. 
abnormal end of task (abend). Termination of a task 
before its completion because of an error condition that 


cannot be resolved by recovery facilities while the task 
is executing. 
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ACB. (1) in VTAM, access method control block. 
(2) In NCP, adapter control block. 


ACB name. (1) The name of an ACB macroinstruction. 
(2) Aname specified in the ACBNAME parameter of a 
VTAM APPL statement. Contrast with network name. 


accept. (1) For a VTAM application program, to estab- 
lish a session with a logical unit (LU) in response to a 
CINIT request from a system services control point 
(SSCP). The session-initiation request may begin when 
a terminal user logs on, a VTAM application program 
issues a macroinstruction, or a VTAM operator issues a 
command. See also acquire (7). (2) In NPM, an SMP 
process that moves distributed code to the distribution 
libraries. 


access method. A technique for moving data between 
main storage and input/output devices. 


access method control block (ACB). A contro! block 
that links an application program to VSAM or VTAM. 


accounting exit routine. in VTAM, an optional installa- 
tion exit routine that collects statistics about session 
initiation and termination. 


ACF. Advanced Communications Function. 


ACFINCP. Advanced Communications Function for the 
Network Contro! Program. Synonym for NCP. 


ACF/SSP. Advanced Communications Function for the 
System Support Programs. Synonym for SSP. 


ACFIVTAM. Advanced Communications Function for 
the Virtual Telecommunications Access Method. 
Synonym for VTAM. 


acquire. (1) For a VTAM application program, to ini- 
tiate and establish a session with another logical unit 
(LU). The acquire process begins when the application 
program issues a macroinstruction. See also accept. 
(2) To take over resources that were formerly con- 
trolled by an access method in another domain, or to 
resume control of resources that were controlled by 
this domain but released. Contrast with release. See 
also resource takeover. 


activate. To make a resource of a node ready to 
perform the functions for which it was designed. Con- 
trast with deactivate. 


active. (1) The state a resource is in when it has been 


activated and is operational. Contrast with inactive, 
pending, and inoperative. (2) Pertaining to a major or 
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minor node that has been activated by VTAM. Most 
resources are activated as part of VTAM start proc- 
essing or as the result of a VARY ACT command. 


active application. The application subsystem cur- 
rently in an extended recovery facility (XRF) session 
with a terminal user. See a/ternate application. 


adapter. Hardware card that allows a device, such as 
a PC, to communicate with another device, such as a 
monitor, a printer, or other I/O device. 


adapter contro! block (ACB). In NCP, a control block 
that contains line control information and the states of 
I/O operations for BSC lines, SS lines, or SDLC links. 


adaptive session pacing. Synonym for adaptive 
session-level pacing. 


adaptive session-level pacing. A form of session-level 
pacing in which session components exchange pacing 
windows that may vary in size during the course of a 
session. This allows transmission to adapt dynamically 
to variations in availability and demand of buffers on a 
session by session basis. Session pacing occurs 
within independent stages along the session path 
according to local congestion at the intermediate 
nodes. Synonymous with adaptive session pacing. 
See pacing, session-level pacing, and virtual route 
pacing. 


adjacent SSCP table. A table containing lists of the 
system services control points (SSCPs) that VTAM can 
be in session with or can use to reach destination 
SSCPs in the same network or in other networks. The 
table is filed in the VTAM definition library. 


adjacent subareas. Two subareas connected by one or 
more links with no intervening subareas. See also 
subarea. 


Advanced Communications Function (ACF). A group of 
IBM licensed programs (principally VTAM, TCAM, NCP, 
and SSP) that use the concepts of Systems Network 
Architecture (SNA), including distribution of function 
and resource sharing. 


alias name. A name defined in a host used to repre- 
sent a logical unit name, logon mode table name, or 
class-of-service name in another network. This name 
is defined to a name translation program when the 
alias name does not match the real name. The alias 
name translation program is used to associate the real 
and alias names. 


alias name translation facility. A function for con- 
verting logical unit names, logon mode table names, 
and class-of-service names used in one network into 
equivalent names to be used in another network. 
Available with NetView or NCCF licensed programs. 


142 VTAM Customization 


“Restricted Materials of IBM” 
Licensed Materials — Property of IBM 


allocate. A logical unit (LU) 6.2 application program 
interface (API) verb used to assign a session to a con- 
versation for the conversation’s use. Contrast with 
deallocate. 


alternate application. The subsystem that is prepared 
to take over a particular active application's extended 
recovery facility (XRF) sessions with terminal users in 
case the application fails. See active application. 


application program. (1) A program written for or by a 
user that applies to the user's work. (2) A program 
used to connect and communicate with stations ina 
network, enabling users to perform application-oriented 
activities. 


apply. in NPM, an SMP process that moves distributed 
code to the system libraries. 


ASCH. * American National Standard Code for Infor- 
mation Interchange. The standard code, using a coded 
character set consisting of 7-bit coded characters (8-bit 
including parity check), used for information inter- 
change among data processing systems, data commu- 
nication systems, and associated equipment. The 
ASCH set consists of control characters and graphic 
characters. 


attaching device. Any device that is physically con- 
nected to a network and can communicate over the 
network. 


authorization exit routine. In VTAM, an optional instal- 
lation exit routine that approves or disapproves 
requests for session initiation. 


automatic logon. (1) A process by which VTAM auto- 
matically creates a session-initiation request to estab- 
lish a session between two logical units (LUs). The 
session will be between a designated primary logical 
unit (PLU) and a secondary logical unit (SLU) that is 
neither queued for nor in session with another PLU. 
See also controlling application program and control- 
ling logical unit. (2) In VM, a process by which a 
virtual machine is initiated by other than the user of 
that virtual machine. For example, the primary VM 
operator’s virtual machine is activated automatically 
during VM initialization. 


autotask. An unattended NetView operator station task 
that does not require a terminal or a logged-on user. 
Autotasks can run independent of VTAM and are typi- 
cally used for automated console operations. Contrast 
with fogged-on operator. 


available. In VTAM, pertaining to a logical unit what is 
active, connected, enabied, and not at its session limit. 


backup session. The session that replaces the failing 


primary extended recovery facility (XRF) session 
between a terminal user and the active subsystem. 
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BASE disk. The virtual disk that contains the text 
decks and macroinstructions for VTAM and VM/SNA 
console support (VSCS). It also contains control files 
and sample files used when running VTAM on the VM 
operating system. See DELTA disk, MERGE disk, RUN 
disk, and ZAP disk. 


bidder. In SNA, the LU-LU half-session defined at 
session activation as having to request and receive 
permission from the other LU-LU half-session to begin 
a bracket. Contrast with first speaker. See also 
bracket protocol and contention. 


Binary Synchronous Communication (BSC). (1) Com- 
munication using binary synchronous line discipline. 

(2) A uniform procedure, using a standardized set of 
contro! characters and control character sequences, for 
synchronous transmission of binary-coded data 
between stations. 


bind. In SNA, a request to activate a session between 
two logical units (LUs). See also session activation 
request. Contrast with UNBIND. 


BIU segment. {n SNA, the portion of a basic informa- 
tion unit (BIU) that is contained within a path informa- 
tion unit (PIU). It consists of either a request/response 
header (RH) followed by all or a portion of a 
request/response unit (RU), or only a portion of an RU. 


blocking of PiUs. In SNA, an optional! function of path 
control that combines multiple path information units 
(PIUs) into a single basic transmission unit (BTU). 


boundary function. (1) A capability of a subarea node 
to provide protocol support for attached peripheral 
nodes, such as: (a) interconnecting subarea path 
control and peripheral path control elements, (b) per- 
forming session sequence numbering for low-function 
peripheral nodes, and (c) providing session-level 
pacing support. (2) The component that provides these 
capabilities. See also boundary node, network 
addressable unit (NAU), peripheral path control, 
Subarea node, and subarea path control. 


boundary node. (1) A subarea node with boundary 
function. See subarea node. See also boundary func- 
tion. (2) The programming component that performs 
FID2 (format identification type 2) conversion, channel 
data link control, pacing, and channel or device error 
recovery procedures for a locally attached station. 
These functions are similar to those performed by a 
network control program for an NCP-attached station. 


bracket protocol. In SNA, a data flow control protocol 
in which exchanges between the two LU-LU half- 
sessions are achieved through the use of brackets, with 
one LU designated at session activation as the first 
speaker and the other as the bidder. The bracket pro- 
tocol involves bracket initiation and termination rules. 
See also bidder and first speaker. 
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BSC. Binary Synchronous Communication. 


buffer. A portion of storage for temporarily holding 
input or output data. 


bypass. To eliminate an attaching device or an access 
unit from a ring network by allowing the data to flow in. 
a path around it. 


call. (1) * (ISO) The action of bringing a computer 
program, a routine, or a subroutine into effect, usually 
by specifying the entry conditions and jumping to an 
entry point. (2) To transfer control to a procedure, 
program, routine, or subroutine. (3) The actions nec- 
essary to make a connection between two stations. 

(4) To attempt to contact a user, regardless of whether 
the attempt is successful. 


call connected packet. A call supervision packet that a 
data circuit-terminating equipment (DCE) transmits to 
indicate to a calling data terminal equipment (DTE) that 
the connection for the call has been completely estab- 
lished. 


call request packet. A call supervision packet that a 
data terminal equipment (DTE) transmits to ask that a 
connection for a call be established throughout the 
network. 


call-accepted packet. * (ISO) Acall supervision 
packet that a called data terminal equipment (DTE) 
transmits to indicate to the data circuit-terminating 
equipment (DCE) that it accepts the incoming call. 


calling. * (ISO) The process of transmitting selection 
signals in order to establish a connection between data 
stations. 


CALLOUT. The logical channel type on which the data 
terminal equipment (DTE) can send a call, but cannot 
receive one. 


CDRM. Cross-domain resource manager. 
CDRSC. Cross-domain resource. 


chain. (1) A group of logically linked records. (2) See 
RU chain. 


channel. * A path along which signals can be sent, for 
example, data channel, output channel. See data 
channel and input/output channel. See also link. 


channel-attached. (1) Pertaining to the attachment of 
devices directly by input/output channels to a host 
processor. (2) Pertaining to devices attached to a con- 
trolling unit by cables, rather than by telecommuni- 
cation lines. Contrast with /ink-attached. Synonymous 
with focal. 
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character-coded. Synonym for unformatted. 
CiCcsS. Customer Information Control System. 
CID. Communication identifier. 


circult switching. (1) * (ISO) A process that, on 
demand, connects two or more data terminal equip- 
ments (OTEs) and permits the exclusive use of a data 
circuit between them until the connection is released. 
(2) Synonymous with /ine switching. (3) See also 
message switching and packet switching. 


class of service (COS). in SNA, a designation of the 
path control network characteristics, such as path 
security, transmission priority, and bandwidth, that 
apply to a particular session. The end user designates 
class of service at session initiation by using a sym- 
bolic name that is mapped into a list of virtual routes, 
any one of which can be selected for the session to 
provide the requested level of service. 


cleanup. A network services request, sent by a system 
services control unit (SSCP) to a logical unit (LU), that 
causes a4 particular LU-LU session with that LU to be 
ended immediately and without the participation of 
either the other LU or its SSCP. 


clear indication packet. A call supervision packet that 
a data circuit-terminating equipment (DCE) transmits to 
inform a data terminal equipment (DTE) that a call has 
been cleared. 


clear request packet. A call supervision packet trans- 
mitted by a data terminal equipment (DTE) to ask that a 
cal! be cleared. 


CNM. Communication network management. 


command. (1) A request from a terminal for the per- 
formance of an cperation or the execution of a partic- 
ular program. (2) In SNA, any field set in the 
transmission header (TH), request header (RH), and 
sometimes portions of a request unit (RU), that initiates 
an action or that begins a protocol; for example: (a) 
Bind Session (session-control request unit), a 
command that activates an LU-LU session, (b) the 
change-direction indicator in the RH of the last RU ofa 
chain, (c) the virtual route reset window indicator ina 
FID4 transmission header. See also VTAM operator 
command. 


command processor. A user-written module designed 
to perform a specific function. Command processors, 
which can be written in assembler or a high-level lan- 
guage (HLL), are invoked as commands. 


communication adapter. An optional hardware 


feature, available on certain processors, that permits 
communication tines to be attached to the processors. 
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communication controller. A type of communication 
control unit whose operations are controlled by one or 
more programs stored and executed in the unit; for 
example, the IBM 3725 Communication Controller. It 
manages the details of line control and the routing of 
data through a network. 


communication Identifier (CID). In VTAM, a key for 

locating the control biccks that represent a session. 
The key is created during the session-establishment 
procedure and deleted when the session ends. 


communication line. Deprecated term for telecommu- 
nication line and transmission line. 


communication management configuration host node. 
The type 5 host processor in a communication manage- 
ment configuration that does all network-contro! func- 
tions in the network except for the control of devices 
channel-attached to data hosts. Synonymous with com- 
munication management host. Contrast with data host 
node. 


communication management host. Synonym for com- 
munication management configuration host node. Con- 
trast with data host. 


communication network management (CNM). The 
process of designing, installing, operating, and man- 
aging the distribution of information and controls 
among end users of communication systems. 


communication network management (CNM) applica- 
tion program. A VTAM application program that issues 
and receives formatted management services request 
units for physical units. For example, the NetView 
program. 


communication network management (CNM) Interface. 
The interface that the access method provides to an 
application program for handling data and commands 
associated with communication system management. 
CNM data and commands are handled across this inter- 
face. 


communication network management (CNM) 
processor. A program that manages one of the func- 
tions of a communications system. A CNM processor is 
executed under contro! of the NetView program. 


component. Any part of a network other than an 
attaching device, such as an access unit. 


composite end node (CEN). A group of nodes made up 
of a single type 5 node and its subordinate type 4 nodes 
that together support type 2.1 protocols. To a type 2.1 
node, a CEN appears as one end node. For example, 
NCP and VTAM act as a composite end node. 


configuration. (1) (TC97) The arrangement of a com- 
puter system or network as defined by the nature, 
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number, and the chief characteristics of its functional 
units. The term may refer to a hardware or a software 
configuration. (2) The devices and programs that 
make up a system, subsystem, or network. (3) In CCP, 
the arrangement of controllers, lines, and terminals 
attached to an IBM 3710 Network Controller. Also, the 
collective set of item definitions that describe such a 
configuration. 


configuration services. In SNA, one of the types of 
network services in the control point (CP) and in the 
physical unit (PU); configuration services activate, 
deactivate, and maintain the status of physica! units, 
links, and link stations. Configuration services also 
shut down and restart network elements and modify 
path control routing tables and address-translation 
tables. See also maintenance services, management 
services, network services, and session services. 


connection. Synonym for physical connection. 


contention. A situation in which two logical units (LUs) 
that are connected by an LU 6.2 session both attempt to 
allocate the session for a conversation at the same 
time. The control operator assigns “winner” and 
“loser” status to the LUs so that processing may con- 
tinue on an orderly basis. The contention loser 
requests permission from the contention winner to allo- 
cate a conversation on the session, and the contention 
winner either grants or rejects the request. See also 
bidder. 


control block. (1) (ISO) Astorage area used by a 
computer program to hold contro! information. (2) In 
the IBM Token-Ring Network, a specifically formatted 
biock of information provided from the application 
program to the Adapter Support Interface to request an 
operation. 


control point (CP). (1) A system services contro! point 
(SSCP) that provides hierarchical control of a group of 
nodes in a network. (2) Acontrol point (CP) local toa 
specific node that provides control of that node, either 
in the absence of SSCP control (for type 2.1 nodes 
engaged in peer to peer communication) or to supple- 
ment SSCP control. 


control program (CP). The VM operating system that 
manages the real processor’s resources and is respon- 
sible for simulating System/370s for individual users. 


controlier. A unit that controls input/output operations 
for one or more devices. 


controlling application program. in VTAM, an applica- 
tion program with which a secondary logical unit (other 
than an application program) is automatically put in 
session whenever the secondary logical unit is avail- 
able. See also automatic logon and controlling logical 
unit. 
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controlling logical unit. In VTAM, a logical unit with 
which a secondary logical unit (other than an applica- 
tion program) is automatically put in session whenever 
the secondary logical unit is available. A controlling 
logical unit can be either an application program or a 
device-type logical unit. See also automatic logon and 
controlling application program. 


conversation. In SNA, a logical connection between 
two transaction programs using an LU 6.2 session. 
Conversations are delimited by brackets to gain exciu- 
sive use of a session. 


converted command. An intermediate form of a 
character-coded command produced by VTAM through 
use of an unformatted system services definition table. 
The format of a converted command is fixed; the unfor- 
matted system services definition table must be con- 
structed in such a manner that the character-coded 
command (as entered by a logical unit) is converted 
into the predefined, converted command format. See 
also unformatted. 


COS. Class of service. 
CP. (1) Control program. (2) Control point. 


cross-domain. In SNA, pertaining to control of 
resources involving more than one domain. 


cross-domain resource (CDRSC). A resource owned 
by a cross-domain resource manager (CDRM) in 
another domain but Known by the CDRM in this domain 
by network name and associated CDRM. 


cross-domain resource manager (CDRM). In VTAM, 
the function in the system services contro! point (SSCP) 
that controls initiation and termination of cross-domain 
sessions. 


cross-network. in SNA, pertaining to control or 
resources involving more than one SNA network. 


cross-network session. An LU-LU or SSCP-SSCP 
session whose path traverses more than one SNA 
network. 


Customer [Information Control System (CICS). A 
licensed program that enables transactions entered at 
remote terminals to be processed concurrently by user- 
written application programs. It also includes facilities 
for building, using, and maintaining data bases. 


data channel. Synonym for input/output channel. See 
channel. 


data host. Synonym for data host node. Contrast with 
communication management configuration host. 


data host node. in a communication management con- 
figuration, a type 5 host node that is dedicated to proc- 
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essing applications and does not control network 
resources, except for its channel-attached or communi- 
cation adapter-attached devices. Synonymous with 
data host. Contrast with communication management 
configuration host node. 


data link. In SNA, synonym for fink. 


data link control (DLC) layer. In SNA, the layer that 
consists of the link stations that schedule data transfer 
over a transmission medium connecting two nodes and 
perform error control for the link connection. Examples 
of data link control are SDLC for serial-by-bit link con- 
nection and data link control for the System/370 
channel. 


data link level. In the hierarchical structure of a data 
station, the conceptual level of control or processing 
logic between high level logic and the data link that 
maintains control of the data link. The data link level 
performs such functions as inserting transmit bits and 
deleting receive bits; interpreting address and control 
fields; generating, transmitting, and interpreting com- 
mands and responses; and computing and interpreting 
frame check sequences. See also packet level and 
physical level. 


data packet. At the interface between a data terminal 
equipment (OTE) and a data circuit-terminating equip- 
ment (DCE), a packet used to transmit user data over a 
virtual circuit. 


DCE clear confirmation packet. A call supervision 
packet that a data circuit-terminating equipment (DCE) 
transmits to confirm that a call has been cleared. 


deactivate. To take a resource of a node out of 
service, rendering it inoperable, or to place it in a state 
in which it cannot perform the functions for which it was 
designed. Contrast with activate. 


deallocate. A logical unit (LU) 6.2 application program 
interface (API) verb that terminates a conversation, 
thereby freeing the session for a future conversation. 
Contrast with allocate. 


default SSCP list. A list of system services control 
points (SSCPs), either in VTAM’s network or another 
network, that can be used when no predefined cross- 
domain resource (CDRSC) or name translation function 
is provided specifying an LU’s owning cross-domain 
resource manager (CDRM). This list is filed as a part of 
an adjacent SSCP table in the VTAM definition library. 


definite response (DR). in SNA, a value in the form-of- 
response-requested field of the request header. The 
value directs the receiver of the request to return a 
response unconditionally, whether positive or negative, 
to that request. Contrast with exception response and 
no response. 
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definition statement. (1) In VTAM, the statement that 
describes an element of the network. (2) In NCP, a 
type of instruction that defines a resource to the NCP. 
See Figure 19, Figure 20, and Figure 21. See also 
macroinstruction. 


operands 
suboperands suboperands 
4 
START A,(B,C),. .KEYWORDI=D, KEYWORD2=(E,F) 
statement positional keyword 
identifier operands operands 


statement 


Figure 19. Example of a Language Statement 


definition statement 


suboperands 


BUILO CA=(ca0[,cal}[,ca2][,ca3]) 
definition keyword 
statement operand 
identifier 


Figure 20. NCP Examples 


definition keyword cperand 
statement 
identifier suboperands 

PU DISCNT=([YES{NO][,FINFJ ) 


definition statement 


VARY NET ACT, IDename ,RNAME=(namel,...,nemel3 


operator positional 
command operands 
operator 


suboperands 


operands 


operator comnand 
Figure 21. VTAM Examples 


DELTA disk. The virtua! disk in a VM operating system 
that contains program temporary fixes (PTFs) that have 
been installed but not merged. See BASE disk, MERGE 
disk, RUN disk, and ZAP disk. 


destination logical unit (DLU). The logical unit to which 
data is to be sent. Contrast with origin logical unit 
(OLU). 


device. An input/output unit such as a terminal, 
display, or printer. See attaching device. 


directory. in VM, a control program (CP) disk that 
defines each virtual machine’s normal configuration. 
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disabled. In VTAM, pertaining to a logical unit (LU) 
that has indicated to its system services control point 
(SSCP) that it is temporarily not ready to establish 
LU-LU sessions. An initiate request for a session with 
a disabled logical unit (LU) can specify that the session 
be queued by the SSCP until the LU becomes enabled. 
The LU can separately indicate whether this applies to 
its ability to act as a primary logical unit (PLU) or a sec- 
ondary logical unit (SLU). See also enabled and inhib- 
ited. 


discarded packet. A packet that is intentionally 
destroyed. 


disconnection. The termination of a physical con- 
nection. 


discontiguous shared segment. An area of virtual 
storage outside the address range of a virtual machine. 
It can contain read-only data or reentrant code. It con- 
nects discontiquous segments to a virtual machine’s 
address space so programs can be fetched. 


display. (1) To present information for viewing, 
usually on a terminal screen or a hard-copy device. 
(2) A device or medium on which information is pre- 
sented, such as a terminal screen. (3) Deprecated 
term for panel. 


DLC. Data link control. 
DLU. Destination logical unit. 


domain. (1) An access method, its application pro- 
grams, communication controllers, connecting lines, 
modems, and attached terminals. (2) In SNA, a system 
services contro! point (SSCP) and the physical units 
(PUs), logical units (LUs), links, link stations, and ali the 
associated resources that the SSCP has the ability to 
control by means of activation requests and deacti- 
vation requests. See system services control point 
domain and type 2.1 node control point domain. See 
also single-domain network and multiple-domain 
network. 


domain operator. !n a multiple-domain network, the 
person or program that controls the operation of the 
resources controlled by one system services control 
point. Contrast with network operator (2). 


downstream. In the direction of data flow from the host 
to the end user. Contrast with upstream. 


Downstream Load Utility (DSLU). A licensed program 
that uses the communication network management 
(CNM) interface to support the load requirements of 
certain type 2 physical units, such as the IBM 3644 
Automatic Data Unit and the IBM 8775 Display Ter- 
minal. 
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drop. inthe IBM Token-Ring Network, a cable that 
leads from a faceplate to the distribution panel ina 
wiring closet. When the IBM Cabling System is used 
with the IBM Token-Ring Network, a drop may form part 
of a lobe. 


dump. (1) Computer printout of storage. (2) To write 
the contents of all or part of storage to an external 
medium as a safeguard against errors or in connection 
with debugging. (3) (ISO) Data that have been 
dumped. 


EBCDIC. * Extended binary-coded decimal inter- 
change code. A coded character set consisting of 8-bit 
coded characters. 


element. (1) A field in the network address. (2) The 
particular resource within a subarea identified by the 
element address. See also subarea. 


element address. in SNA, a value in the element 
address field of the network address identifying a spe- 
cific resource within a subarea. See subarea address. 


Emulation Program (EP). An IBM control program that 
allows a channel-attached 3705 or 3725 communication 
controller to emulate the functions of an IBM 2701 Data 
Adapter Unit, an IBM 2702 Transmission Control, or an 
IBM 2703 Transmission Control. See also network 
control program. 


enabled. In VTAM, pertaining to a logical unit (LU) that 
has indicated to its system services control point 
(SSCP) that it is now ready to establish LU-LU sessions. 
The LU can separately indicate whether this prevents it 
from acting as a primary logical unit (PLU) or as a sec- 
ondary logical! unit (SLU). See also disabled and inhib- 
ited. 


end node. A type 2.1 node that does not provide any 
intermediate routing or session services to any other 
node. For example, APPC/PC is an end node. See 
composite end node, node, and type 2.71 node. 


end user. in SNA, the ultimate source or destination of 
application data flowing through an SNA network. An 
end user may be an application program or a terminal 
operator. 


entry point. An SNA node that provides distributed 
network management support. It may be a type 2, type 
2.1, type 4, or type 5 node. It sends SNA-formatted 
network management data about itself and the 
resources it controls to a focal point for centralized 
processing, and it receives and executes focal point ini- 
tiated commands to manage and control its resources. 


EP. Emulation Program. 


ER. (1) Explicit route. (2) Exception response. 
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ESTAE. Extended specify task abnormal exit. 


exception response (ER). in SNA, a value in the form- 
of-response-requested field of a request header (RH). 
An exception response is sent only if a request is unac- 
ceptable as received or cannot be processed. Contrast 
with definite response and no response. See also neg- 
ative response. 


EXEC. Ina VM operating system, a user-written 
command file that contains CMS commands, other 
user-written commands, and execution contro! state- 
ments, such as branches. 


exit routine. Any of several types of special-purpose 
user-written routines. See accounting exit routine, 
authorization exit routine, logon-interpret routine, 
virtual route selection exit routine, EXLST exit routine, 
and APL exit routine. 


EXLST exit routine. in VTAM, a routine whose address 
has been placed in an exit list (EXLST) control block. 
The addresses are placed there with the EXLST macro- 
instruction, and the routines are named according to 
their corresponding operand; hence DFASY exit 
routine, TPEND exit routine, RELREQ exit routine, and 
so forth. All exit list routines are coded by the VTAM 
application programmer. Contrast with RPL exit 
routine. 


explicit route (ER). In SNA, the path control network 
elements, including a specific set of one or more trans- 
mission groups, that connect two subarea nodes. An 
explicit route is identified by an origin subarea 
address, a destination subarea address, an explicit 
route number, and a reverse explicit route number. 
Contrast with virtual route (VR). See also path and 
route extension. 


explicit route length. In SNA, the number of trans- 
mission groups in an explicit route. 


extended architecture (XA). An extension to 
System/370 architecture that takes advantage of contin- 
uing high performance enhancements to computer 
system hardware. 


extended recovery facility (XRF). Software designed to 
minimize the effect of failures in MVS, VTAM, the host 
processor, or IMS/VS on sessions between IMS/VS and 
designated terminals. It provides an alternate sub- 
system to take over failing sessions. 


extended specify task abnormal exit (ESTAE). An MVS 
macroinstruction that provides recovery capability and 
gives control to the user-specified exit routine for proc- 
essing, diagnosing an abend, or specifying a retry 
address. 


feature. A particular part of an IBM product that a cus- 
tomer can order separately. 
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field-formatted. Pertaining to a request or response 
that is encoded into fields, each having a specified 
format such as binary codes, bit-significant flags, and 
symbolic names. Contrast with character-coded. 


first speaker. in SNA, the LU-LU half-session defined 
at session activation as: (1) able to begin a bracket 
without requesting permission from the other LU-LU 
half-session to do so, and (2) winning contention if both 
half-sessions attempt to begin a bracket simultane- 
ously. Contrast with bidder. See also bracket protocol. 


flow control. In SNA, the process of managing the rate 
at which data traffic passes between components of the 
network. The purpose of flow control is to optimize the 
rate of flow of message units, with minimum congestion 
in the network; that is, to neither overflow the buffers at 
the receiver or at intermediate routing nodes, nor leave 
the receiver waiting for more message units. See also 
adaptive session-level pacing, pacing, session-level 
pacing, and virtual route pacing. 


formatted system services. A portion of VTAM that 
provides certain system services as a result of 
receiving a field-formatted command, such as an Ini- 
tiate or Terminate command. Contrast with unfor- 
matted system services (USS). See also 
tieid-formaited. 


frame. (1) The unit of transmission in some local area 
networks, including the IBM Token-Ring Network. It 
includes delimiters, control characters, information, 
and checking characters. (2) In SDLC, the vehicle for 
every command, every response, and all information 
that is transmitted using SDLC procedures. 


gateway. (1) The combination of machines and pro- 
grams that provide address translation, name trans- 
lation, and system services control point (SSCP) 
rerouting between independent SNA networks to allow 
those networks to communicate. A gateway consists of 
one gateway NCP and at Jeast one gateway SSCP. 

(2) In the IBM Token-Ring Network, a device and its 
associated software that connect a local area network 
to another local area network or a host that uses dif- 
ferent logical link protocols. 


gateway NCP. An NCP that performs address trans- 
lation to allow cross-network session traffic. The 
gateway NCP connects two or more independent SNA 
networks. Synonymous with gateway node. 


gateway node. Synonym for gateway NCP. 


gateway SSCP. An SSCP that is capable of cross- 
network session initiation, termination, takedown, and 
session outage notification. A gateway SSCP is in 
session with the gateway NCP; it provides network 
name translation and assists the gateway NCP in 
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setting up alias network addresses for cross-network 
sessions. 


GCS. Group control system. 


generation. The process of assembling and link 
editing definition statements so that resources can be 
identified to all the necessary programs in a network. 


generic unbind. Synonym for session deactivation 
request. 


group. In the NetView/PC program, to identify a set of 
application programs that are to run concurrently. 


group control system (GCS). A component of VM that 
provides multiprogramming and shared memory 
support to virtual machines. It is a saved system 
intended for use with SNA products. 


half-session. in SNA, a component that provides func- 
tion management data (FMD) services, data flow 
control, and transmission control for one of the ses- 
sions of a network addressable unit (NAU). See also 
primary half-session and secondary half-session. 


help panel. An online display that tells you how to use 
a command or another aspect of a product. See task 
panel. 


hierarchy. In the NetView program, the resource 
types, display types, and data types that make up the 
organization, or levels, in a network. 


host node. A node providing an application program 
interface (API) and a common application interface. 
See boundary node, node, peripheral node, subarea 
host node, and subarea node. See also boundary func- 
tion and node type. 


ILU. Initiating logical unit. 


IMS. Information Management System/Virtual Storage. 
Synonymous with /MS/VS. 


IMS/VS. Information Management System/Virtual 
Storage. Synonym for /MS. 


inactive. Describes the state of a resource that has not 
been activated or for which the VARY INACT command 
has been issued. Contrast with active. See also inop- 
erative. 


incoming call packet. A call supervision packet trans- 
mitted by a data circuit-terminating equipment (DCE) to 
inform a called data terminal equipment (DTE) that 
another OTE has requested a call. 


information (i) format. A format used for information 
transfer. 
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Information Management System (IMS). A general 
purpose system whose full name is Information Man- 
agement System/Virtual Storage (IMS/VS). It enhances 
the capabilities of OS/VS for batch processing and tele- 
communication and allows users to access a computer- 
maintained data base through remote terminals. 


Information/Management. A feature of the 
Information/System licensed program that provides 
interactive systems management applications for 
problem, change, and configuration management. 


inhibited. In VTAM, pertaining to a logical unit (LU) 
that has indicated to its system services control point 
(SSCP) that it is not ready to establish LU-LU sessions. 
An initiate request for a session with an inhibited LU 
will be rejected by the SSCP. The LU can separately 
indicate whether this applies to its ability to act as a 
primary logical unit (PLU) or as a secondary logical 
unit (SLU). See also enabled and disabled. 


initial program toad (IPL). (1) The initialization proce- 
dure that causes an operating system to commence 
operation. (2) The process by which a configuration 
image is loaded into storage at the beginning of a work 
day or after a system malfunction. (3) The process of 
loading system programs and preparing a system to 
run jobs. 


initiate. A network services request sent from a logical 
unit (LU) to a system services control point (SSCP) 
requesting that an LU-LU session be established. 


inoperative. The condition of a resource that has been 
active, but is not. The resource may have failed, 
received an INOP request, or is suspended while a 
reactivate command is being processed. See also 
inactive. 


input/output channel. (1) (ISO) In a data processing 
system, a functional unit that handles the transfer of 
data between internal and peripheral equipment. (2) In 
a computing system, a functional unit, controlled by a 
processor, that handles the transfer of data between 
processor storage and local peripheral devices. Syn- 
onymous with data channel. See channel. See also 
link, 


interconnection. See SNA network interconnection. 


interface. * A shared boundary. An interface might be 
a hardware component to link two devices or it might 
be a portion of storage or registers accessed by two or 
more computer programs. 


intermediate routing node (IRN). in SNA, a subarea 
node with intermediate routing function. 


intermediate SSCP. An SSCP along a session initiation 


path that owns neither of the LUs involved in a cross- 
network LU-LU session. 
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interpret table. !n VTAM, an installation-defined corre- 
lation list that translates an argument into a string of 
eight characters. Interpret tables can be used to trans- 
late logon data into the name of an application program 
for which the logon is intended. 


IPL. (1) * Initial program loader. (2) Initial program 
load. 


IRN. Intermediate routing node. 


item. in CCP, any of the components, such as commu- 
nication controllers, lines, cluster controllers, and ter- 
minals, that comprise an IBM 3710 Network Controller 
configuration. 


keyword. (1) (TC97) A lexical unit that, in certain con- 
texts, characterizes some language construction. (2) * 
One of the predefined words of an artificial language. 
(3) One of the significant and informative words in a 
title or document that describes the content of that doc- 
ument. (4) A name or symbol! that identifies a param- 
eter. (5) A part of a command operand that consists of 
a specific character string (such as DSNAME=). See 
also definition statement and keyword operand. Con- 
trast with positional operand. 


keyword operand. An operand that consists of a 
keyword followed by one or more values (such as 
DSNAME = HELLO). See also definition statement. 
Contrast with positional operand. 


keyword parameter. A parameter that consists of a 
keyword followed by one or more values. 


LAN. An industry-wide acronym for local area 
network. 


line. See communication line. 

line control discipline. Synonym for link protocol. 
line discipline. Synonym for link protocol. 

line switching. Synonym for circuit switching. 


Jink. In SNA, the combination of the link connection 
and the link stations joining network nodes; for 
example: (1) a System/370 channel and its associated 
protocols, (2) a serial-by-bit connection under the 
control of Synchronous Data Link Control (SDLC). A 
link connection is the physical medium of transmission. 
A link, however, is both logical and physical. Synony- 
mous with data link. See Figure 22 on page 151. 


link connection segment. A portion of the configuration 
that is located between two resources listed consec- 
utively in the service point command service (SPCS) 
query link configuration request list. 
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link level. (1) A part of Recommendation X.25 that 
defines the link protoco! used to get data into and out of 
the network across the duplex link connecting the sub- 
scriber’s machine to the network node. LAP and LAPB 
are the link access protocols recommended by the 
CCITT. (2) See data link level. 


link protocol. (1) See protoco/. (2) See also /ink level. 


link station. (1) In SNA, the combination of hardware 
and software that allows a node to attach to and 
provide control for a link. (2) In VTAM, a named 
resource within a subarea node that represents 
another subarea node that is attached by a subarea 
link. In the resource hierarchy, the link station is sub- 
ordinate to the subarea link. 


fink-attached. Pertaining to devices that are physically 
connected by a telecommunication line. Contrast with 
channel-attached. Synonymous with remote. 


load module. (iSO) A program unit that is suitable for 
loading into main storage for execution; it is usually the 
output of a linkage editor. 


local. Pertaining to a device that is attached to a con- 
trolling unit by cables, rather than by a telecommuni- 
cation line. Synonymous with channel-attached. 


local address. In SNA, an address used in a peripheral 
node in place of an SNA network address and trans- 
formed to or from an SNA network address by the 
boundary function in a subarea node. 


local area network (LAN). (1) A network in which a set 
of devices are connected to one another for communi- 
cation and that can be connected to a larger network. 
See also token ring. (2) A network in which communi- 
cations are limited to a moderately sized geographic 
area such as a single office building, warehouse, or 
campus, and which do not generally extend across 
public rights-of-way. Contrast with wide area network. 


local non-SNA major node. In VTAM, a major node 
whose minor nodes are channel-attached non-SNa ter- 
minals. 


local SNA major node. in VTAM, a major node whose 
minor nodes are channel-attached peripheral nodes. 


logged-on operator. A NetView operator station task 
that requires a terminal and a logged-on user. Contrast 
with autotask. 


logical unit (LU). !n SNA, a port through which an end 
user accesses the SNA network and the functions pro- 
vided by system services control points (SSCPs). An 
LU can support at least two sessions—one with an 
SSCP and one with another LU—and may be capable of 
supporting many sessions with other LUs. See also 
network addressable unit (NAU), peripheral LU, phys- 
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Subarea Host Node 


Type 5 PU 


Boundary LU 
Function 


Channel Subarea Link 
Subarea Path Control Po eee ee Subarea Path Control 


Peripheral Host Node 


Type 2.1 PU 


Peripheral Path Control 


Figure 22. Links and Path Controls 


ical unit (PU), system services control point (SSCP), 
primary logical unit (PLU), and secondary logical unit 
(SLU). 


logical unit (LU) services. In SNA, capabilities ina 
logical unit to: (1) receive requests from an end user 
and, in turn, issue requests to the system services 
control point (SSCP) in order to perform the requested 
functions, typically for session initiation; (2) receive 
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Another 
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Link 


Communication Controller 
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Boundary 
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Peripheral Path Control 


SDLC Peripheral 
Links 


Type 2 


Type 2.1 


requests from the SSCP, for example to activate LU-LU 
sessions via Bind Session requests; and (3) provide 
session presentation and other services for LU-LU ses- 
sions. See also physical unit (PU) services. 


logical unit (LU) 6.2. A type of logical unit that sup- 
ports general communication between programs in a 
distributed processing environment. LU 6.2 is charac- 
terized by (1) a peer relationship between session part- 
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ners, (2) efficient utilization of a session for multiple 
transactions, (3) comprehensive end-to-end error proc- 
essing, and (4) a generic application program interface 
(API) consisting of structured verbs that are mapped 
into a product implementation. 


logmode table. Synonym for logon mode table. 


logon. In VTAM, an unformatted session initiation 
request for a session between two logical units. See 
automatic logon and simulated logon. See also 
session-initiation request. 


logon data. In VTAM: (1) The user data portion of a 
field-formatted or unformatted session-initiation 
request. (2) The entire logon sequence or message 
from a logical unit (LU). Synonymous with /ogon 
message. 


logon message. Synonym for fogon data. 


logon mode. {in VTAM, a subset of session parameters 
specified in a logon mode table for communication with 
a logical unit. See also session parameters. 


logon mode table. in VTAM, a set of entries for one or 
more logon modes. Each logon mode is identified by a 
logon mode name. Synonymous with /ogmode table. 


logon-interpret routine. in VTAM, an installation exit 
routine, associated with an interpret table entry, that 
translates logon information. It may also verify the 
logon. 


LU. Logical unit. 


LU type. In SNA, the classification of an LU-LU session 
in terms of the specific subset of SNA protocols and 
options supported by the logical units (LUs) for that 
session, namely: 


The mandatory and optional values allowed in the 
session activation request. 


The usage of data stream controls, function man- 
agement headers (FMHs), request unit (RU) param- 
eters, and sense codes. 


Presentation services protocols such as those 
associated with FMH usage. 


LU types 0, 1, 2, 3, 4, 6.1, 6.2, and 7 are defined. 

LU 6.2. Logical unit 6.2. 

LU-LU session. In SNA, a session between two Iogical 
units (LUs) in an SNA network. It provides communi- 
cation between two end users, or between an end user 
and an LU services component. 


LU-LU session type. A deprecated term for LU type. 
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macroinstruction. (1) An instruction that when exe- 
cuted causes the execution of a predefined sequence of 
instructions in the same source language. (2) In 
assembler programming, an assembler language state- 
ment that causes the assembler to process a prede- 
fined set of statements called a macro definition. The 
statements normally produced from the macro defi- 
nition replace the macroinstruction in the program. 

See also definition statement. 


maintain system history program (MSHP). A program 
that facilitates the process of installing and servicing a 
VSE system. 


maintenance services. In SNA, one of the types of 
network services in system services control points 
(SSCPs) and physical units (PUs). Maintenance ser- 
vices provide facilities for testing links and nodes and 
for collecting and recording error information. See 
also configuration services, management services, 
network services, and session services. 


major node. In VTAM, a set of resources that can be 
activated and deactivated as a group. See node and 
minor node. 


management services. in SNA, one of the types of 
network services in control points (CPs) and physical 
units (PUs). Management services are the services 
provided to assist in the management of SNA networks, 
such as problem management, performance and 
accounting management, configuration management 
and change management. See also configuration ser- 
vices, maintenance services, network services, and 
session services. 


maximum SSCP rerouting count. The maximum 
number of times a session initiation request will be 
rerouted to intermediate system services control points 
(SSCPs) before the request reaches the destination 
SSCP. This count is used to prevent endless rerouting 
of session initiation requests. 


MDR. Miscellaneous data record. 


MERGE disk. The virtual disk in the VM operating 
system that contains program temporary fixes (PTFs) 
after the VMFMERGE EXEC is invoked. See BASE disk, 
DELTA disk, RUN disk, and ZAP disk. 


message. (1) (TC97) A group of characters and 
control bit sequences transferred as an entity. (2) In 
VTAM, the amount of function management data (FMD) 
transferred to VTAM by the application program with 
one SEND request. 


message switching. (1) * (ISO) In a data network, the 
process of routing messages by receiving, storing, and 
forwarding complete messages. (2) The technique of 
receiving a complete message, storing, and then for- 
warding it unaltered to its destination. 
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migration. Installing a new version or release of a 
program when an earlier version or release is already 
in place. 


minor node. In VTAM, a uniquely-defined resource 
within a major node. See node and major node. 


miscellaneous data record (MDR). A record of a 
network hardware error recorded by the NCP and sent 
to the VTAM host that owns the failing component. 
Then VTAM writes the error on the operating system 
error data set. 


mode name. A symbolic name for a set of session 
characteristics. For LU 6.2, a mode name and a 
partner LU name together define a group of parallel 
sessions having the same characteristics. 


module. * A program unit that is discrete and identifi- 
able with respect to compiling, combining with other 
units, and loading; for example, the input to or output 
from an assembier, compiler, linkage editor, or execu- 
tive routine. 


monitor. In the IBM Token-Ring Network, the function 
required to initiate the transmission of a token on the 
ring and to provide soft-error recovery in case of lost 
tokens, circulating frames, or other difficulties. The 
capability is present in all ring stations. 


MSHP. Maintain system history program. 


Multiple Virtual Storage (MVS). An IBM licensed 
program whose full name is the Operating 
System/Virtual Storage (OS/VS) with Multiple Virtual 
Storage/System Product for System/370. It is a soft- 
ware operating system controlling the execution of pro- 
grams. 


Multiple Virtual Storage for Extended Architecture 
(MVS/XA). An IBM licensed program whose full name 
is the Operating System/Virtual Storage (OS/VS) with 
Multiple Virtual Storage/System Product for Extended 
Architecture. Extended architecture allows 31-bit 
storage addressing. MVS/XA is a software operating 
system controlling the execution of programs. 


multiple-domain network. In SNA, a network with more 
than one system services control point (SSCP). Con- 
trast with single-domain network. 


MVS. Multiple Virtual Storage. 


MVS/ESA. Multiple Virtual Storage/Enterprise 
Systems Architecture. 


MVS/XA. Multiple Virtual Storage for Extended Archi- 
tecture. 


name translation. In SNA network interconnection, 
converting logical unit names, logon mode table 
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names, and class-of-service names used in one 
network into equivalent names to be used in another 
network. This function can be provided through the 
NetView program and invoked by a gateway system 
services control point (SSCP) when necessary. See 
also alias name. 


NAU. Network addressable unit. 


NCP. (1) Network Control Program (IBM licensed 
program). Its full name is Advanced Communications 
Function for the Network Control Program. Synony- 
mous with ACF/NCP. (2) Network control program 
(genera! term). 


negative response (NR). in SNA, a response indicating 
that a request did not arrive successfully or was not 
processed successfully by the receiver. Contrast with 
positive response. See exception response. 


NetView. A system 370-based IBM licensed program 
used to monitor a network, manage it, and diagnose its 
problems. 


NetView-NetView task (NNT). The task under which a 
cross-domain NetView operator session runs. See 
operator station task. 


network. (1) (TC97) An interconnected group of 
nodes. (2) In data processing, a user application 
network. See path contro! network, public network, 
SNA network, and user-application network. 


network address. in SNA, an address, consisting of 
subarea and element fields, that identifies a link, a link 
station, or a network addressable unit. Subarea nodes 
use network addresses; peripheral nodes use local 
addresses. The boundary function in the subarea node 
to which a peripheral node is attached transforms local 
addresses to network addresses and vice versa. See 
local address. See also network name. 


network addressable unit (NAU). In SNA, a logical unit, 
a physical unit, or a system services control point. It is 
the origin or the destination of information transmitted 
by the path control network. Each NAU has a network 
address that represents it to the path contro! network. 
See also network name, network address, and path 
control network. 


network control program. A program, generated by 
the user from a library of IBM-supplied modules, that 
controls the operation of a communication controller. 


Network Control Program (NCP). An iBM licensed 
program that provides communication controller 
support for single-domain, multiple-domain, and inter- 
connected network capability. Its full name is 
Advanced Communications Function for the Network 
Control Program. 
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network identifier (network ID). The network name 
defined to NCPs and hosts to indicate the name of the 
network in which they reside. It is unique across all 
communicating SNA networks. 


Network Logica! Data Manager (NLDM). An IBM 
licensed program that collects and correlates session- 
related data and provides online access to this informa- 
tion. It runs as an NCCF communication network 
management (CNM) application program. Its function 
is included and enhanced in NetView’s session 
monitor. 


network management vector transport (NMVT). A 
management services request/response unit (RU) that 
flows over an active session between physical unit 
management services and contro! point management 
services (SSCP-PU session). 


network name. (1) In SNA, the symbolic identifier by 
which end users refer to a network addressable unit 
(NAU), a link, or a link station. See also network 
address. (2) In a multiple-domain network, the name 
of the APPL statement defining a VTAM application 
program is its network name and it must be unique 
across domains. Contrast with ACB name. See unin- 
terpreted name. 


network operator. (1) A person or program respon- 
sible for controlling the operation of all or part of a 
network. (2) The person or program that controls all 
the domains in a multipte-domain network. Contrast 
with domain operator. 


Network Problem Determination Application (NPDA). 
An IBM licensed program that helps you identify 
network problems, such as hardware, software, and 
microcode, from a central control point using interac- 
tive display techniques. !t runs as an NCCF communi- 
cation network management (CNM) application 
program. its function is included and enhanced in 
NetView’s hardware monitor. 


network services (NS). In SNA, the services within 
network addressable units (NAUs) that control network 
operation through SSCP-SSCP, SSCP-PU, and SSCP-LU 
sessions. See configuration services, maintenance 
services, management services, and session services. 


network services (NS) header. In SNA, a 3-byte field in 
a function management data (FMD) request/response 
unit (RU) flowing in an SSCP-LU, SSCP-PU, or 
SSCP-SSCP session. The network services header is 
used primarily to identify the network services category 
of the request unit (RU) (for example, configuration ser- 
vices, session services) and the particular request 
code within a category. 


Network Terminal Option (NTO). An IBM licensed 


program used in conjunction with NCP that allows 
certain non-SNA devices to participate in sessions with 
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SNA application programs in the host processor. NTO 
converts non-SNA protocol to SNA protocol when data 
is sent to the host from a non-SNA device and recon- 
verts SNA protocol to non-SNA protocol when data is 
sent back to the device. 


NLOM. Network Logical Data Manager. 
NMVT. Network management vector transport. 


no response. In SNA, a value in the form-of-response- 
requested field of the request header (RH) indicating 
that no response is to be returned to the request, 
whether or not the request is received and processed 
successfully. Contrast with definite response and 
exception response. 


node. (1) In SNA, an endpoint of a link or junction 
common to two or more links in a network. Nodes can 
be distributed to host processors, communication con- 
trotlers, cluster controllers, or terminals. Nodes can 
vary in routing and other functional capabilities. See 
boundary node, host node, peripheral node, and 
Subarea node. (2) In VTAM, a point in a network 
defined by a symbolic name. See major node and 
minor node. 


node name. in VTAM, the symbolic name assigned to 
a specific major or minor node during network defi- 
nition. 


node type. in SNA, a designation of a node according 
to the protocols it supports and the network address- 
able units (NAUs) that it can contain. Five types are 
defined: 1, 2.0, 2.1, 4, and 5. Type 1, type 2.0, and type 
2.1 nodes are peripheral nodes; type 4 and type 5 
nodes are subarea nodes. See also type 2.7 node. 


notify. A network services request that is sent by an 
SSCP to a logical unit (LU) to inform the LU of the status 
of a procedure requested by the LU. 


NPDA. Network Probiem Determination Application. 
NTO. Network Terminal Option. 
OLU. Origin logical unit. 


ontine. Stored in a computer and accessible from a 
terminal. 


open. (1) In the IBM Token-Ring Network, to make an 
adapter ready for use. (2) A break in an electrical 
circuit. 


operand. (1) (ISO) An entity on which an operation is 
performed. (2) * That which is operated upon. An 
operand is usually identified by an address part of an 
instruction. (3) Information entered with a command 
name to define the data on which a command 
processor operates and to control the execution of the 


LY43-0046-01 © Copyright IBM Corp. 1884, 1880 


“Restricted Materials of IBM" 
Licensed Materials — Property of IBM 


command processor. (4) An expression to whose 
value an operator is applied. See also definition state- 
ment, keyword, keyword parameter, and parameter. 


operator. (1) In a language statement, the lexical 
entity that indicates the action to be performed on oper- 
ands. See also definition statement. (2) A person who 
operates a machine. See network operator. (3) A 
person or program responsible for managing activities 
controlled by a given piece of software such as MVS, 
the NetView program, or IMS. See fogged-on operator 
and network operator See also autotask and operator 
Station task. 


operator station task (OST). The NetView task that 
establishes and maintains the online session with the 
network operator. There is one operator station task 
for each network operator who logs on to the NetView 
program. See NetView-NetView task. 


origin logical unit (OLU). The logical unit from which 
data is sent. Contrast with destination logical unit 
(DLU). 


pacing. !n SNA, a technique by which a receiving com- 
ponent controls the rate of transmission of a sending 
component to prevent overrun or congestion. See 
session-level pacing, send pacing, and virtual route 
(VR) pacing. See also flow control. 


pacing group. In SNA, (1) The path information units 
(PiUs) that can be transmitted on a virtual route before 
a virtual-route pacing response is received, indicating 
that the virtual route receiver is ready to receive more 
PiUs on the route. Synonymous with window. (2) The 
requests that can be transmitted on the normal flow in 
one direction on a session before a session-level 
pacing response is received, indicating that the 
receiver is ready to accept the next group of requests. 


pacing group size. In SNA, (1) The number of path 
information units (PIUs) in a virtual route pacing group. 
The pacing group size varies according to traffic con- 
gestion along the virtual route. Synonymous with 
window size. (2) The number of requests in a session- 
level pacing group. 


pacing response. !n SNA, an indicator that signifies a 
receiving component's readiness to accept another 
pacing group; the indicator is carried in a response 
header (RH) for session-level pacing, and in a trans- 
mission header (TH) for virtual route pacing. 


packet. (ISO) A sequence of binary digits, including 
data and control signals, that is transmitted and 
switched as a composite whole. The data, control 
signals, and possibly error control information are 
arranged in a specific format. See ca/l-accepted 
packet, call-connected packet, call request packet, call 
supervision packets, clear indication packet, clear 
request packet, data packet, DCE clear confirmation 
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packet, discarded packet, incoming call packet, permit 
packet, and reset packet. 


packet level. (1) The packet format and control proce- 
dures for exchange of packets containing control infor- 
mation and user data between data terminal equipment 
(DTE) and data circuit-terminating equipment (DCE). 
See also data link level and physical level. (2) A part 
of Recommendation X.25 that defines the protocol for 
establishing logical connections between two DTEs and 
for transferring data on these connections. 


packet major node. In VTAM, a set of minor nodes 
representing resources, such as switched virtual cir- 
cuits and permanent virtual circuits, attached through 
an X.25 port. See major node. 


packet mode operation. Synonym for packet switching. 


packet switching. (1) (ISO) The process of routing 
and transferring data by means of addressed packets 
so that a channel is occupied only during the trans- 
mission of a packet. On completion of the trans- 
mission, the channel is made available for the transfer 
of other packets. (2) Synonymous with packet mode 
operation. See also circuit switching. 


page. (1) The portion of a panel that is shown ona 
display surface at one time. (2) To move back and 
forth among the pages of a multiple-page pane!. See 
also scrol/. (3) (ISO) In a virtual storage system, a 
fixed-length block that has a virtual address and that 
can be transferred between real storage and auxiliary 
storage. (4) To transfer instructions, data, or both 
between real storage and external page or auxiliary 
storage. 


panel. (1) A formatted display of information that 
appears on a terminal screen. See help panel and task 
panel. Contrast with screen. (2) In computer graphics, 
a display image that defines the locations and charac- 
teristics of display fields on a display surface. 


parallel sessions. {in SNA, two or more concurrently 
active sessions between the same two logical units 
(LUs) using different pairs of network addresses. Each 
session can have independent session parameters. 


parameter. (1) (ISO) A variable that is given a con- 
stant value for a specified application and that may 
denote the application. (2) An item in a menu for 
which the user specifies a value or for which the 
system provides a value when the menu is interpreted. 
(3) Data passed to a program or procedure by a user 
or another program, namely as an operand in a lan- 
guage statement, as an item in a menu, or as a shared 
data structure. See also keyword, keyword parameter, 
and operand. 


path. (1) In SNA, the series of path control network 
components (path control and data link control) that are 
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traversed by the information exchanged between two 
network addressable units (NAUs). See also explicit 
route (ER), route extension, and virtual route (VR). 

(2) In VTAM when defining a switched major node, a 
potential dial-out port that can be used to reach that 
node. (3) In the NetView/PC program, a complete line 
in a configuration that contains all of the resources in 
the service point command service (SPCS) query link 
configuration request list. 


path control (PC). The function that routes message 
units between network addressable units (NAUs) in the 
network and provides the paths between them. It con- 
verts the BIUs from transmission control (possibly seg- 
menting them) into path information units (PIUs) and 
exchanges basic transmission units (BTUs) and one or 
more PiUs with data link control. Path control differs 
for peripheral nodes, which use focal addresses for 
routing, and subarea nodes, which use network 
addresses for routing. See peripheral! path control and 
subarea path control. See also /ink, peripheral node, 
and subarea node. 


path control (PC) network. In SNA, the part of the SNA 
network that includes the data link contro! and path 
control layers. See SNA network and user application 
network. See also boundary function. 


path information unit (PIU). In SNA, a message unit 
consisting of a transmission header (TH) alone, or of a 
TH followed by a basic information unit (BIU) or a BIU 
segment. See also transmission header. 


PCID. Procedure-correlation identifier. 


peripheral host node. A node that provides an applica- 
tion program interface (API) for running application 
programs but does not provide SSCP functions and is 
not aware of the network configuration. The peripheral 
host node does not provide subarea node services. It 
has boundary function provided by its adjacent 
subarea. See boundary node, host node, node, periph- 
eral node, subarea host node, and subarea node. See 
also boundary function and node type. 


peripheral LU.. In SNA, a logical unit representing a 
peripheral node. 


peripheral node. In SNA, a node that uses focal 
addresses for routing and therefore is not affected by 
changes in network addresses. A peripheral node 
requires boundary-function assistance from an adja- 
cent subarea node. A peripheral node is a physical 
unit (PU) type 1, 2.0, or 2.1 node connected to a 
subarea node with boundary function within a subarea. 
See boundary node, host node, node, peripheral host 
node, subarea host node, and subarea node. See also 
boundary function and node type. 


peripheral path contro!. The function in a peripheral 
node that routes message units between units with 
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local addresses and provides the paths between them. 
See path control and subarea path control. See also 
boundary function, peripheral node, and subarea node. 


peripheral PU. In SNA, a physical unit representing a 
peripheral node. 


permit packet. At the interface between a data ter- 
minal equipment (DTE) and a data circuit-terminating 
equipment (DCE), a packet used to transmit permits 
over a virtual circuit. 


physical connection. {n VTAM, a point-to-point con- 
nection or multipoint connection. Synonymous with 
connection. 


physical level. The mechanical, electrical, functional, 
and procedural media used to activate, maintain, and 
deactivate the physical link between the data terminal 
equipment (DTE) and the data circuit-terminating equip- 
ment (DCE). See also data link level and packet level. 


physical unit (PU). In SNA, a type of network address- 
able unit (NAU). A physical unit (PU) manages and 
monitors the resources (such as attached links) of a 
node, as requested by a system services control point 
(SSCP) through an SSCP-PU session. An SSCP acti- 
vates a session with the physical unit in order to indi- 
rectly manage, through the PU, resources of the node 
such as attached links. See also peripheral PU and 
subarea PU. 


physical unit (PU) services. In SNA, the components 
within a physical unit (PU) that provide configuration 
services and maintenance services for SSCP-PU ses- 
sions. See also logical unit (LU) services. 


PIU. Path information unit. 
PLU. Primary logical unit. 


polling. (1) * Interrogation of devices for purposes 
such as to avoid contention, to determine operational 
status, or to determine readiness to send or receive 
data. (2) (TC97} The process whereby stations are 
invited, one at a time, to transmit. 


positional operand. An operand in a language state- 
ment that has a fixed position. See also definition 
Statement. Contrast with keyword operand. 


positive response. A response indicating that a 
request was received and processed. Contrast with 
negative response. 


primary haif-session. In SNA, the half-session that 
sends the session activation request. See also primary 
logical unit. Contrast with secondary haif-session. 


primary logical unit (PLU). In SNA, the logical unit (LU) 
that contains the primary half-session for a particular 
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LU-LU session. Each session must have a PLU and 
secondary logical unit (SLU). The PLU is the unit 
responsible for the bind and is the controlling LU for 
the session. A particular LU may contain both primary 
and secondary half-sessions for different active LU-LU 
sessions. Contrast with secondary logical unit (SLU). 


primary session. An extended recovery facility (XRF) 
session between the active application subsystem and 
a terminal user. 


problem determination. The process of identifying the 
source of a problem; for example, a program compo- 
nent, a machine failure, telecommunication facilities, 
user or contractor-installed programs or equipment, an 
environment failure such as a power loss, or a user 
error. 


procedure-correlation identifier (PCID). In SNA, a 
value used by a contro! point to correlate requests and 
replies. 


protection key. An indicator that appears in the 
current program status word whenever an associated 
task has control of the system. This indicator must 
match the storage keys of all main storage locks that 
the task is to use. 


protocol. (1) (CCITT/ITU) A specification for the 
format and relative timing of information exchanged 
between communicating parties. (2) (TC97) The set of 
rules governing the operation of functional units of a 
communication system that must be followed if commu- 
nication is to be achieved. (3) In SNA, the meanings of, 
and the sequencing rules for, requests and responses 
used for managing the network, transferring data, and 
synchronizing the states of network components. Syn- 
onymous with /ine contro! discipline and line discipline. 
See also bracket protocol and fink protocol. 


PU. Physical unit. 


PU-PU flow. In SNA, the exchange between physical 
units (PUs) of network control requests and responses. 


public network. A network established and operated 
by communication common carriers or telecommuni- 
cation Administrations for the specific purpose of pro- 
viding circuit-switched, packet switched, and 
leased-circuit services to the public. Contrast with 
user-application network. 


realname. The name by which a logical unit (LU), 
logon mode table, or class-of-service (COS) table is 
known within the SNA network in which it resides. 


real network address. The address by which a logical 


unit (LU) is known within the SNA network in which it 
resides. 
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receive pacing. In SNA, the pacing of message units 
that the component is receiving. See also send pacing. 


RECFMS. Record formatted maintenance statistics. 
RECMS. Record maintenance statistics. 


Recommendation X.21 (Geneva 1980). A Consultative 
Committee on International Telegraph and Telephone 
(CCITT) recommendation for a general purpose inter- 
face between data terminal equipment and data circuit 
equipment for synchronous operations on a public data 
network. 


Recommendation X.25 (Geneva 1980). A Consultative 
Committee on International Telegraph and Telephone 
(CCITT) recommendation for the interface between data 
terminal equipment and packet-switched data net- 
works. See also packet switching. 


record. (1) (ISO) In programming languages, an 
aggregate that consists of data objects, possibly with 
different attributes, that usually have identifiers 
attached to them. In some programming languages, 
records are called structures. (2) (TC97) Aset of data 
treated as a unit. (3) A set of one or more related data 
items grouped for processing. (4) In VTAM, the unit of 
data transmission for record mode. A record repres- 
ents whatever amount of data the transmitting node 
chooses to send. 


record formatted maintenance statistics (RECFMS). A 
statistical record built by an SNA controller and usually 
solicited by the host. 


record maintenance statistics (RECMS). An SNA error 
event record built from an NCP or line error and sent 
unsolicited to the host. 


reentrant. The attribute of a program or routine that 
allows the same copy of the program or routine to be 
used concurrently by two or more tasks. For example, 
the 3710 Network Controller routines may be reentrant. 


release. For VTAM, to relinquish control of resources 
(communication controllers or physical units). See also 
resource takeover. Contrast with acquire (2). 


remote. Concerning the peripheral parts of a network 
not centrally linked to the host processor and generally 
using telecommunication lines with public right-of-way. 


request header (RH). in SNA, control information pre- 
ceding a request unit (RU). See also request/response 
header (RH). 


request parameter list (RPL). In VTAM, a contro! block 
that contains the parameters necessary for processing 
a request for data transfer, for establishing or termi- 
nating a session, or for some other operation. 
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request unit (RU). in SNA, a message unit that con- 
tains control information, end-user data, or both. 


request/response header (RH). In SNA, control infor- 
mation, preceding a request/response unit (RU), that 
specifies the type of RU (request unit or response unit) 
and contains control information associated with that 
RU. 


request/response unit (RU). In SNA, a generic term for 
a request unit or a response unit. See also request unit 
(RU) and response unit. 


reset. On a virtual circuit, reinitialization of data flow 
contro!. At reset, all data in transit are eliminated. 


reset packet. A packet used to reset a virtual circuit at 
the interface between the data terminal equipment 
(DTE) and the data circuit-terminating equipment 
(DCE). 


resource. (1) Any facility of the computing system or 
operating system required by a job or task, and 
including main storage, input/output devices, the proc- 
essing unit, data sets, and control or processing pro- 
grams. (2) In the NetView program, any hardware or 
software that provides function to the network. 


resource takeover. In VTAM, action initiated by a 
network operator to transfer control of resources from 
one domain to another. See also acquire (2} and 
release. See takeover. 


response. A reply represented in the control field of a 
response frame. It advises the primary or combined 
station of the action taken by the secondary or other 
combined station to one or more commands. See also 
command. 


response header (RH). In SNA, a header, optionally 
followed by a response unit (RU), that indicates 
whether the response is positive or negative and that 
may contain a pacing response. See also negative 
response, pacing response, and positive response. 


response time. (1) The amount of time it takes after a 
user presses the enter key at the terminal until the 
reply appears at the terminal. (2) For response time 
monitoring, the time from the activation of a transaction 
until a response is received, according to the response 
time definition coded in the performance class. 


response unit (RU). In SNA, a message unit that 
acknowledges a request unit; it may contain prefix 
information received in a request unit. If positive, the 
response unit may contain additional information (such 
as session parameters in response to Bind Session), or 
if negative, contains sense data defining the exception 
condition. 
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return code. * A code [returned from a program] used 
to influence the execution of succeeding instructions. 


RH. Request/response header. 


ring. A network configuration where a series of 
attaching devices are connected by unidirectional 
transmission links to form a closed path. 


route. See explicit route and virtual route. 


route extension (REX). In SNA, the path control 
network components, including a peripheral link, that 
make up the portion of a path between a subarea node 
and a network addressable unit (NAU) in an adjacent 
peripheral node. See also path, explicit route (ER) and 
virtual route (VA). 


routing. The assignment of the path by which a 
message will reach its destination. 


RPL. Request parameter list. 


RPL exit routine. In VTAM, an application program exit 
routine whose address has been placed in the EXIT 
field of a request parameter list (RPL). VTAM invokes 
the routine to indicate that an asynchronous request 
has been completed. See EXLST exit routine. 


RU. Request/response unit. 


RU chain. In SNA, a set of related request/response 
units (RUs) that are consecutively transmitted on a par- 
ticular norma! or expedited data flow. The request RU 
chain is the unit of recovery: if one of the RUs in the 
chain cannot be processed, the entire chain is dis- 
carded. Each RU belongs to only one chain, which has 
a beginning and an end indicated by means of control 
bits in request/response headers within the RU chain. 
Each RU can be designated as first-in-chain (FIC), tast- 
in-chain (LIC), middle-in-chain (MIC), or only-in-chain 
(OIC). Response units and expedited-flow request units 
are always sent as only-in-chain. 


RUN disk. The virtual disk that contains the VTAM and 
VM/SNA console support (VSCS) load libraries, 
program temporary fixes (PTFs) and user-written mod- 
ifications from the ZAP disk. See BASE disk, DELTA 
disk, MERGE disk, and ZAP disk. 


same-domain. Refers to communication between enti- 
ties in the same SNA domain. Contrast with cross- 
domain. See also single-domain network. 


SAW data. Synonym for session awareness (SAW) 
data. 


$C. Session control. 
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screen. An illuminated display surface; for example, 
the display surface of a CRT or plasma panel. Contrast 
with panei. 


scroll. To move all or part of the display image verti- 
cally to display data that cannot be observed within a 
single display image. See also page (2). 


SDLC. Synchronous Data Link Control. 


secondary half-session. In SNA, the half-session that 
receives the session-activation request. See also sec- 
ondary logical unit (SLU). Contrast with primary half- 
session. 


secondary logical unit (SLU). In SNA, the logical unit 
(LU) that contains the secondary half-session for a par- 
ticular LU-LU session. An LU may contain secondary 
and primary half-sessions for different active LU-LU 
sessions. Contrast with primary logical unit (PLU). 


secondary logical unit (SLU) key. A key-encrypting key 
used to protect a session cryptography key during its 
transmission to the secondary half-session. 


segment. (1) In the IBM Token-Ring Network, a 
section of cable between components or devices on the 
network. A segment may consist of a single patch 
cable, multiple patch cables connected together, or a 
combination of building cable and patch cables con- 
nected together. (2) See fink connection segment. 


send pacing. In SNA, pacing of message units that a 
component is sending. See also receive pacing. 


service point (SP). An entry point that supports appli- 
cations that provide network management for 
resources not under the direct contro! of itself as an 
entry point. Each resource is either under the direct 
control of another entry point or not under the direct 
control of any entry point. A service point accessing 
these resources is not required to use SNA sessions 
(unlike a focal point). A service point is needed when 
entry point support is not yet available for some 
network management function. 


service reminder (SR). in the NetView/PC program, a 
notification set by the operator that is displayed on a 
panel and logs a specified message. 


session. in SNA, a logical connection between two 
network addressable units (NAUs) that can be acti- 
vated, tailored to provide various protocols, and deacti- 
vated, as requested. Each session Is uniquely 
identified in a transmission header (TH) by a pair of 
network addresses, identifying the origin and destina- 
tion NAUs of any transmissions exchanged during the 
session. See haif-session, LU-LU session, SSCP-LU 
session, SSCP-PU session, and SSCP-SSCP session. 
See also LU-LU session type and PU-PU flow. 
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session activation request. In SNA, a request that acti- 
vates a session between two network addressable units 
(NAUs) and specifies session parameters that control 
various protocols during session activity; for example, 
BIND and ACTPU. Contrast with session deactivation 
request. 


session awareness (SAW) data. Data collected by the 
NetView program about a session that includes the 
session type, the names of session partners, and infor- 
mation about the session activation status. it is col- 
lected for LU-LU, SSCP-LU, SSCP-PU, and SSCP-SSCP 
sessions and for non-SNA terminals not supported by 
NTO. It can be displayed in various forms, such as 
most recent sessions lists. 


session control (SC). In SNA, (1) One of the compo- 
nents of transmission control. Session control is used 
to purge data flowing in a session after an unrecover- 
able error occurs, to resynchronize the data flow after 
such an error, and to perform cryptographic verifica- 
tion. (2) A request unit (RU) category used for requests 
and responses exchanged between the session control 
components of a session and for session activation and 
deactivation requests and responses. 


session deactivation request. In SNA, a request that 
deactivates a session between two network address- 
able units (NAUs); for example, UNBIND and DACTPU. 
Synonymous with generic unbind. Contrast with 
session activation request. 


session management exit routine. An installation- 
supplied VTAM exit routine that performs authorization, 
accounting, and gateway path selection functions. 


session monitor. The component of the NetView 
program that collects and correlates session-related 
data and provides online access to this information. 


session parameters. !n SNA, the parameters that 
specify or constrain the protocols (such as bracket pro- 
tocol and pacing) for a session between two network 
addressable units. See also fogon mode. 


session partner. In SNA, one of the two network 
addressable units (NAUs) having an active session. 


session services. In SNA, one of the types of network 
services in the control point (CP) and in the logical unit 
(LU). These services provide facilities for an LU or a 
network operator to request that the SSCP initiate or 
terminate sessions between logical units. See config- 
uration services, maintenance services, and manage- 
ment services. 


session-establishment request. In VTAM, a request to 
an LU to establish a session. For the primary logical 
unit (PLU) of the requested session, the session- 
establishment request is the CINIT sent from the 
system services control point (SSCP) to the PLU. For 
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the secondary logical unit (SLU) of the requested 
session, the session-establishment request is the BIND 
sent from the PLU to the SLU. 


session-initiation request. In SNA, an Initiate or logon 
request from a logical unit (LU) to a control point (CP) 
that an LU-LU session be activated. 


session-level pacing. In SNA, a flow control! technique 
that permits a receiver to control the data transfer rate 
(the rate at which it receives request units) on the 
normal flow. It is used to prevent overloading a 
receiver with unprocessed requests when the sender 
can generate requests faster than the receiver can 
process them. See also pacing and virtual route 
pacing. 


shared. Pertaining to the availability of a resource to 
more than one use at the same time. 


simulated logon. A session-initiation request gener- 
ated when a VTAM application program issues a 
SIMLOGON macroinstruction. The request specifies a 
logical unit (LU) with which the application program 
wants a session in which the requesting application 
program will act as the primary logical unit (PLU). 


single-domain network. In SNA, a network with one 
system services control point (SSCP). Contrast with 
multiple-domain network. 


SLU. Secondary logical unit. 
SMF. System management facility. 
SNA. Systems Network Architecture. 


SNA network. The part of a user-application network 
that conforms to the formats and protocols of Systems 
Network Architecture. It enables reliable transfer of 
data among end users and provides protocols for con- 
trolling the resources of various network configura- 
tions. The SNA network consists of network 
addressable units (NAUs), boundary function compo- 
nents, and the path control network. 


SNA network interconnection. The connection, by 
gateways, of two or more independent SNA networks to 
allow communication between logical units in those 
networks. The individual-:SNA networks retain their 
independence. 

SP. Service point. 

SR. Service reminder. 


SSCP. System services control point. 


SSCP ID. In SNA, a number that uniquely identifies a 
system services contro! point (SSCP). The SSCP ID is 


160 VTAM Customization 


“Restricted Materials of IBM” 
Licensed Materials — Property of IBM 


used in session activation requests sent to physical 
units (PUs) and other SSCPs. 


SSCP rerouting. In SNA network interconnection, the 
technique used by the gateway system services control 
point (SSCP) to send session-initiation request units 
(RUs), by way of a series of SSCP-SSCP sessions, from 
one SSCP to another, until the owning SSCP is reached. 


SSCP-LU session. In SNA, a session between a 
system services control point (SSCP) and a logical! unit 
(LU); the session enables the LU to request the SSCP to 
help initiate LU-LU sessions. 


SSCP-PU session. in SNA, a session between a 
system services contro! point (SSCP) and a physical 
unit (PU); SSCP-PU sessions allow SSCPs to send 
requests to and receive status information from indi- 
vidual nodes in order to control the network configura- 
tion. 


SSCP-SSCP session. in SNA, a session between the 
system services control point (SSCP) in one domain 
and the SSCP in another domain. An SSCP-SSCP 
session is used to initiate and terminate cross-domain 
LU-LU sessions. 


SSP. System Support Programs (IBM licensed 
program). Its full name is Advanced Communications 
Function for System Support Programs. Synonymous 
with ACF/SSP. 


ST. Session configuration screen abbreviation. 


start option. in VTAM, a user-specified or 
IBM-supplied option that determines certain conditions 
that are to exist during the time a VTAM system is 
operating. Start options can be predefined or specified 
when VTAM is started. 


statement. A language syntactic unit consisting of an 
operator, or other statement identifier, followed by one 
or more operands. See definition statement. 


station. (1) One of the input or output points of a 
network that uses communication facilities; for 
example, the telephone set in the telephone system or 
the point where the business machine interfaces with 
the channel! on a leased private line. (2) One or more 
computers, terminals, or devices at a particular 
location. 


subarea. A portion of the SNA network consisting of a 
subarea node, any attached peripheral nodes, and their 
associated resources. Within a subarea node, all 
network addressable units, links, and adjacent link 
Stations (in attached peripheral or subarea nodes) that 
are addressable within the subarea share a common 
subarea address and have distinct element addresses. 
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subarea address. in SNA, a value in the subarea field 
of the network address that identifies a particular 
subarea. See also element address. 


subarea host node. A host node that provides both 
subarea function and an application program interface 
(API) for running application programs. It provides 
system services control point (SSCP) functions, 
subarea node services, and is aware of the network 
configuration. See boundary node, communication 
management configuration host node, data host node, 
host node, node, peripheral node, and subarea node. 
See also boundary function and node type. 


subarea node. In SNA, a node that uses network 
addresses for routing and whose routing tables are 
therefore affected by changes in the configuration of 
the network. Subarea nodes can provide gateway func- 
tion, and boundary function support for peripheral 
nodes. Type 4 and type 5 nodes are subarea nodes. 
See boundary node, host node, node, peripheral node, 
and subarea host node. See also boundary function 
and node type. : 


subarea path control. The function in a subarea node 
that routes message units between network address- 
able units (NAUs) and provides the paths between 
them. See path control and peripheral path control. 
See also boundary function, peripheral node, and 
subarea node. 


subarea PU. in SNA, a physical unit (PU) in a subarea 
node. 


subsystem. A secondary or subordinate system, 
usually capable of operating independent of, or asyn- 
chronously with, a controlling system. 


supervisor. The part of a control program that coordi- 
nates the use of resources and maintains the flow of 
processing unit operations. 


switched major node. in VTAM, a major node whose 
minor nodes are physical units and logical units 
attached by switched SOLC links. 


Synchronous Data Link Control! (SDLC). A discipline 
for managing synchronous, code-transparent, 
serial-by-bit information transfer over a link con- 
nection. Transmission exchanges may be duplex or 
half-duplex over switched or nonswitched links. The 
configuration of the link connection may be point-to- 
point, multipoint, or loop. SDLC conforms to subsets of 
the Advanced Data Communication Control Procedures 
(ADCCP) of the American National Standards Institute 
and High-Level Data Link Control (HDLC) of the Interna- 
tional Standards Organization. 


system management facility (SMF). A standard feature 


of MVS that collects and records a variety of system 
and job-related information. 
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system services contro} point (SSCP). In SNA, a 
central location point within an SNA network for man- 
aging the configuration, coordinating network operator 
and problem determination requests, and providing 
directory support and other session services for end 
users of the network. Multiple SSCPs, cooperating as 
peers, can divide the network into domains of control, 
with each SSCP having a hierarchical control relation- 
ship to the physical units and logical units within its 
domain. 


system services control point (SSCP) domain. The 
system services control point and the physical units 
(PUs), logical units (LUs), links, link stations and ail! the 
resources that the SSCP has the ability to control by 
means of activation requests and deactivation 
requests. 


System Support Programs (SSP). An IBM licensed 
program, made up of a collection of utilities and small 
programs, that supports the operation of the NCP. 


Systems Network Architecture (SNA). The description 
of the logical structure, formats, protocols, and opera- 
tional sequences for transmitting information units 
through and controlling the configuration and operation 
of networks. 


takeover. The process by which the failing active sub- 
system is released from its extended recovery facility 
(XRF) sessions with terminal users and replaced by an 
alternate subsystem. See resource takeover. 


task. A basic unit of work to be accomplished by a 
computer. The task is usually specified to a control 
program in a multiprogramming or multiprocessing 
environment. 


task panel. Online display from which you communi- 
cate with the program in order to accomplish the pro- 
grams function, either by selecting an option provided 
on the panel or by entering an explicit command. See 
help panel. 


TCAS. Terminal contro! address space. 


telecommunication line. Any physical medium such as 
a wire or microwave beam, that is used to transmit 
data. Synonymous with transmission line. 


teletypewriter exchange service (TWX). Teletypewriter 
service in which suitably arranged teletypewriter 
stations are provided with lines to a central office for 
access to other such stations throughout the U.S. and 
Canada. Both baudot and ASCll-coded machines are 
used. Business machines may also be used with 
certain restrictions. 


terminal. A device that is capable of sending and 
receiving information over a link; it is usually equipped 
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with a keyboard and some kind of display, such as a 
screen or a printer. 


terminal control address space (TCAS). The part of 
TSO/VTAM that provides logon services for TSO/VTAM 
users. 


TERMINATE. In SNA, a request unit that is sent by a 
logical unit (LU) to its system services control point 
(SSCP) to cause the SSCP to start a procedure to end 
one or more designated LU-LU sessions. 


TH. Transmission header. 


threshold. In the NetView program, refers to a per- 
centage value set for a resource and compared to a 
calculated error-to-traffic ratio. 


threshold. In NPM, high or low values supplied by the 
user to monitor data and statistics being collected. 


time sharing option (TSO). An optional configuration of 
the operating system that provides conversational time 
sharing from remote stations. 


time sharing option for VTAM (TSO/VTAM). An 
optional configuration of the operating system that pro- 
vides conversational time sharing from remote stations 
in a network using VTAM. 


token. A sequence of bits passed from one device to 
another along the token ring. When the token has data 
appended to it, it becomes a frame. 


token ring. A network with a ring topology that passes 
tokens from one attaching device to another. For 
example, the IBM Token-Ring Network. 


transmission control (TC) layer. In SNA, the layer 
within a half-session that synchronizes and paces 
session-level data traffic, checks session sequence 
numbers of requests, and enciphers and deciphers 
end-user data. Transmission control has two compo- 
nents: the connection point manager and session 
control. See also haif-session. 


transmission group (TG). In SNA, a group of links 
.between adjacent subarea nodes, appearing as a 
single logical link for routing of messages. A trans- 
mission group may consist of one or more SDLC links 
(parallel links) or of a single System/370 channel. 


transmission header (TH). In SNA, control information, 
optionally followed by a basic information unit (BIU) or 
a BIU segment, that is created and used by path control 
to route message units and to control their flow within 
the network. See also path information unit. 


transmission line. Synonym for telecommunication 
line. 
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transmission priority. In SNA, a rank assigned to a 
path information unit (PIU) that determines its preced- 
ence for being selected by the transmission group 
control component of path control for forwarding to the 
next subarea node of the route used by the PIU. 


TSO. Time sharing option. 
TSO/VTAM. Time sharing option for VTAM. 
TWX. Teletypewriter exchange service. 


type 2.1 node (T2.1 node). A node that can attach to an 
SNA network as a peripheral node using the same pro- 
tocols as type 2.0 nodes. Type 2.1 nodes can be 
directly attached to one another using peer-to-peer pro- 
tocols. See end node, node, and subarea node. See 
also node type. 


type 2.1 node (T2.1 node) control point domain. The 
CP, its logical units (LUs), links, link stations, and all 
resources that it activates and deactivates. 


UNBIND. In SNA, a request to deactivate a session 
between two logical units (LUs). See also session 
deactivation request. Contrast with BIND. 


unformatted. [n VTAM, pertaining to commands (such 
as LOGON or LOGOFF) entered by an end user and 
sent by a logical unit in character form. The character- 
coded command must be in the syntax defined in the 
user’s unformatted system services definition table. 
Synonymous with character-coded. Contrast with field- 
formatted. 


unformatted system services (USS). In SNA products, 
a system services control point (SSCP) facility that 
translates a character-coded request, such as a logon 
or logoff request into a field-formatted request for proc- 
essing by formatted system services and translates 
field-formatted replies and responses into character- 
coded requests for processing by a logical unit. Con- 
trast with formatted system services. See also 
converted command. 


uninterpreted name. In SNA, a character string that a 
system services control point (SSCP) is able to convert 
into the network name of a logical unit (LU). Typically, 
an uninterpreted name is used in a logon or Initiate 
request from a secondary logical! unit (SLU) to identify 
the primary logical unit (PLU) with which the session is 


‘requested. 


upstream. In the direction of data flow from the end 
user to the host. Contrast with downstream. 


user. Anyone who requires the services of a com- 
puting system. 


user exit. A point in an IBM-supplied program at which 
a user routine may be given control. 
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user exit routine. A user-written routine that receives 
control at predefined user exit points. User exit rou- 
tines can be written in assembler or a high-level lan- 
guage (HLL). 


user-application network. A configuration of data proc- 
essing products, such as processors, controllers, and 
terminals, established and operated by users for the 
purpose of data processing or information exchange, 
which may use services offered by communication 
common carriers or telecommunication Adminis- 
trations. Contrast with public network. 


USERVAR. Contains an application name used to 
route a session-establishment request to the currently 
active application subsystem. 


USS. Unformatted system services. 


value. (1) (TC97) A specific occurrence of an attri- 
bute, for example, “blue” for the attribute “color.” (2) A 
quantity assigned to a constant, a variable, a param- 
eter, or a symbol. 


variable. in the NetView command list language, a 
character string beginning with & that is coded ina 
command list and is assigned a value during execution 
of the command list. 


vector. The MAC frame information field. 


verb. (1) In SNA, the general name for a transaction 
program’s request for communication services. (2) In 
VTAM, a programming language element in the logical 
unit (LU) 6.2 application program interface (API) that 
causes an LU 6.2 function to be performed. 


virtual machine. A functiona! simulation of a computer 
and its associated devices. 


Virtual Machine (VM). A licensed program whose full 
name is the Virtual Machine/System Product (VM/SP). 
It is a software operating system that manages the 
resources of a real processor to provide virtual 
machines to end users. As a time-sharing system 
control program, it consists of the virtual machine 
control program (CP), the conversationa! monitor 
system (CMS), the group control system (GCS), and the 
interactive problem contro! system (IPCS). 


virtual route (VR). In SNA, a logical connection (1) 
between two subarea nodes that is physically realized 
as a particular explicit route, or (2) that is contained 
wholly within a subarea node for intranode sessions. A 
virtual route between distinct subarea nodes imposes a 
transmission priority on the underlying explicit route, 
provides flow control through virtual-route pacing, and 
provides data integrity through sequence numbering of 
path information units (PIUs). See also explicit route 
(ER), path, and route extension. 
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virtual route (VR) pacing. in SNA, a flow control tech- 
nique used by the virtual route control component of 
path control at each end of a virtual route to control the 
rate at which path information units (PIUs) flow over the 
virtual route. VR pacing can be adjusted according to 
traffic congestion in any of the nodes along the route. 
See also pacing and session-level pacing. 


virtual route pacing response (VRPRS). A non- 
sequenced, supervisory path information unit (PIU) that 
flows at network priority. It may overtake 
VR-sequenced PIUs and consists of a transmission 
header with no basic information unit (BIU) data. 


virtuat route selection exit routine. [In VTAM, an 
optional installation exit routine that modifies the list of 
virtual routes associated with a particular class of 
service before a route is selected fot a requested 
LU-LU session. 


virtual storage. (ISO) The notion of storage space that 
may be regarded as addressable main storage by the 
user of a computer system in which virtual addresses 
are mapped into real addresses. The size of virtual 
storage is limited by the addressing scheme of the 
computer system and by the amount of auxiliary 
storage available, not by the actual number of main 
storage locations. 


Virtual Storage Extended (VSE). An IBM ticensed 
program whose full name is the Virtual Storage 
Extended/Advanced Function. It is a software oper- 
ating system controlling the execution of programs. 


Virtual Telecommunications Access Method (VTAM). 
An IBM licensed program that controls communication 
and the flow of data in an SNA network. It provides 
single-domain, multiple-domain, and interconnected 
network capability. 


VIT. VTAM internal! trace. 


VM. Virtual Machine. Its full name is Virtual 
Machine/System Product. Synonymous with VM/SP. 


VM/ESA.. Virtual Machine/Enterprise Systems Archi- 
tecture. 


VM/SNA console support (VSCS). A VTAM component 
for the VM environment that provides Systems Network 
Architecture (SNA) support. It allows SNA terminals to 
be virtual machine consoles. 


VM/SP. Virtual Machine/System Product. Synonym for 
VM. 


VR. Virtual route. 


VSCS. VM/SNA console support. 
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VSE. Virtual Storage Extended. Synonymous with 
VSE/Advanced Functions. 


VSE/Advanced Functions. The basic operating system 
support needed for a VSE-controlled installation. 
Synonym for VSE. 


VSE/ESA. Virtual Storage Extended/Enterprise 
Systems Architecture. 


VTAM. Virtual Telecommunications Access Method 
(IBM licensed program). Its full name is Advanced 
Communications Function for the Virtual Telecommuni- 
cations Access Method. Synonymous with ACF/VTAM. 


VTAM definition. The process of defining the user 
application network to VTAM and modifying 
IBM-defined characteristics to suit the needs of the 
user. 


VTAM internal trace (VIT). A trace used in VTAM to 
collect data on channel !/O, use of locks, and storage 
management services. 


VTAM operator. A person or program authorized to 
issue VTAM operator commands. See domain oper- 
ator, program operator, and network operator (2). 


VTAM operator command. A command used to 
monitor or control a VTAM domain. See also definition 
statement. 


VTAM Terminal 1/O Coordinator (VTIOC). The part of 
TSO/VTAM that converts TSO TGET, TPUT, TPG, and 
terminal control macroinstructions into SNA request 
units. 
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VTIOC. VTAM Terminal I/O Coordinator. 


wide area network. A network that provides data com- 
munication capability in geographic areas larger than 
those serviced by local area networks. Wide area net- 
works may extend across public rights-of-way. Con- 
trast with focal area network. 


window. (1) In SNA, synonym for pacing group. 

(2) On a visual display terminal, a small amount of 
information in a framed-in area on a panel that over- 
lays part of the panel. (3) In data communication, the 
number of data packets a data terminal equipment 
(DTE) or data circuit-terminating equipment (DCE) can 
send across a logical channel! before waiting for 
authorization to send another data packet. The window 
is the main mechanism of pacing, or flow control, of 
packets. 


window size. (1) The specified number of frames of 
information that can be sent before receiving an 
acknowledgment response. (2) In SNA, synonym for 
pacing group size. 

X.21. See Recommendation X.21 (Geneva 1980). 

XA. Extended architecture. 

XRF. Extended recovery facility. 

ZAP disk. The virtual disk in the VM operating system 
that contains the user-written modifications to VTAM 


code. See BASE disk, DELTA disk, MERGE disk, and 
RUN disk. 
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Bibliography 


VTAM Publications 


VTAM V3R3 Publications 


The following paragraphs describe the library for VTAM 
V3R3 running under MVS, VM, and VSE. 


VTAM Directory of Migration Information (GC31-6429) 


This manual contains an overview of the new functions 
in VTAM V3R3. For each function, it includes a brief 
description and references to the manuals which 
contain new information related to the function. 


VTAM Network Implementation Guide (SC31-6404) 


This manual contains information about how to install 
VTAM, how to define a network to VTAM, how to test 
your network definitions, and how to tune VTAM. Use 
this manual in conjunction with VTAM Resource Defi- 
nition Reference. 


VTAM Resource Definition Reference (SC31-6412) 


This manual contains the VTAM definition statements 
and start options. It also has information on the oper- 
ands of NCP definition statements that affect VTAM. To 
assist VM users, this book contains an appendix 
describing VSCS start options. Use this book in con- 
junction with the VTAM Network Implementation Guide. 


VTAM Storage Estimates (SK2T-2010, a diskette) 


This diskette helps you estimate the storage require- 
ments for VTAM. It contains an interactive program 

that guides you step-by-step through the process for 
estimating storage. 


VTAM Customization (LY43-0046) 


This manual enables a system programmer to cus- 
tomize VTAM. It discusses VTAM, VSCS, and 
TSO/VTAM installation exit routines, the replaceable 
constants module, and the communication network 
management (CNM) routing table. 


VTAM Operation (SC31-6408) 

This manual enables a system programmer to prepare 
a “run book" for a VTAM network. This book also 
serves as a reference manual to programmers and 
operators requiring detailed information about specific 


operator commands. 


VTAM Messages and Codes (S$C31-6405) 
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This manual contains, in alphanumerical order, all 
messages and codes issued by VITAM. These mes- 
sages include VTAM messages for network operators, 
TSO/VTAM messages for network operators, 
TSO/VTAM messages for terminal users, USS mes- 
sages for terminal users, and VSCS messages. This 
manual can be inserted into the operating system mes- 
sages manual, if desired, or used as a stand-alone 
manual. 


VTAM Programming (SC31-6409) 


This manual describes how to use VTAM macroin- 
structions to send data to and receive data from (1) a 
terminal in either the same or a different domain, or (2) 
another application program in either the same or a dif- 
ferent domain. Also included is a dictionary of VTAM 
macroinstructions. 


VTAM Programming for LU 6.2 (SC31-6410) 


This manual describes the VTAM LU 6.2 programming 
interface for host application programs. This manual 
applies to programs that use only LU 6.2 sessions or 
that use LU 6.2 sessions along with other session 
types. (Only LU 6.2 sessions are covered in this 
manual, however.) 


VTAM Diagnosis (LY43-0042) 


This manual assists system programmers in identifying 
a VTAM problem, classifying it, and collecting informa- 
tion about the problem in preparation for calling the 
IBM Support Center. The information collected 
includes traces, dumps, and other problem documenta- 
tion. 


VTAM Data Areas for MVS (LY43-0043) 
VTAM Data Areas for VM (LY43-0045) 
VTAM Data Areas for VSE (LY43-0053) 


These manuals describe VTAM data areas and can be 
used to read a VTAM dump. They are intended for IBM 
programming service representatives and customer 
personnel who are diagnosing problems with VTAM. 


VTAM Reference Summary (LY43-0047) 


This manual is designed as a quick reference for 
system programmers. This manual contains selected 
reference information that includes VTAM and VSCS 
commands, VTAM definition statements, VTAM start 
options, VTAM macroinstructions, and VTAM and VSCS 
trace formats. 
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Planning and Reference for NetView, NCP, and VTAM 
(SC31-6092) 


This manual describes how to plan for NetView V2R1, 
NCP V5R3, SSP V3R5, and VTAM V3R3. {ft explains the 
functions available with NetView, NCP, and VTAM, the 
advantages of using them in different situations, and 
how to plan for the functions readers want to use. The 
reference part of the manual contains cross-product or 
cross-task reference information, which may or may 
not be related to planning. The manual also contains 
NCP storage estimates. 


Bibliography and Master Index for NetView, NCP, and 
VTAM (GC31-6430) (when available) 


This book contains a list of manuals that might be 
useful to someone planning, installing, or using a 
network that contains NetView V1R3, NCP V5R3, SSP 
V3R5, and VTAM V3R3. !t also contains an index of 
topics discussed in the products’ libraries. Each entry 


in the index is followed by the titles of the manuals dis- 
cussing that topic. 


VTAM V3R2 Publications 


You may order additional copies of the VTAM V3R2 
publications by the following order numbers. 


Note: Several of these manuals also contain informa- 
tion about VTAM V3R1.2 for VM and VSE, V3R1.1 for 
MVS and VM, and V3R1 for VSE. 

VTAM Installation and Resource Definition (SC23-0111) 
VTAM Customization (LY30-5614) 


VTAM Directory of Programming Interfaces for Cus- 
tomers (GC31-6403) 


VTAM Operation (SC23-0113) 

VTAM Messages and Codes (SC23-01 14) 
VTAM Programming (SC23-0115) 

VTAM Programming for LU 6.2 (SC30-3400) 
VTAM Diagnosis (LY30-5601) 

VTAM Data Areas for MVS (LY30-5592) 
VTAM Data Areas for VM (LY30-5593) 
VTAM Data Areas for VSE (Y30-5594) 
VTAM Reference Summary (LY30-5600) 


VTAM V3R2 Enhancements (LD35-0270) 
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VTAM Version 3 for VM/9370 (SD35-027 1) 


VTAM V3R1.2 Publications 


You may order additional copies of the VTAM V3R1.2 
publications by the following order numbers: 


VTAM Expanded Network Capabilities Support 
(LD21-0019) 


VTAM Directory of Programming Interfaces for Cus- 
tomers (GC31-6402) 


VTAM V3R1.1 Publications 


You may order additional copies of the VTAM V3R1.1 
publications by the following order numbers: 


VTAM Installation and Resource Definition (SC23-0111) 
VTAM Customization (SC23-0112) 

VTAM Operation (SC23-0113) 

VTAM Message and Codes (ST23-0114) 

VTAM Programming (SC23-0115) 

VTAM Diagnosis Guide (SC23-0116) 

VTAM Diagnosis Reference (LY30-5582) 

VTAM Data Areas for MVS (LY30-5584) 

VTAM Data Areas for VM (LY30-5583) 


VTAM Reference Summary (SC23-0135) 


VTAM V3R1 Publications 


You may order additional copies of the VTAM V3R1 
publications by using the following pseudonumbers: 


VTAM Installation and Resource Definition (ST23-0110) 
VTAM Customization (ST23-0112) 

VTAM Operation (ST23-0113) 

VTAM Programming (ST23-0115) 

VTAM Diagnosis Reference (LT/70-5582) 

VTAM Message and Codes (ST23-0114) 


The following VTAM V3R1 publications are still 
orderable by their original order numbers: 


VTAM Messages and Codes for VM (SC30-3275) 
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VTAM Data Areas for MVS (LY30-5581) 
VTAM Data Areas for VM (LY30-5580) 
VTAM Data Areas for VSE (LY30-5579) 


VTAM Library Supplement for X.21 SHM/IMPS 
(SD21-0010) 


Related Publications 


NetView Release 3 Publications 


The fotiowing fist shows the publications associated 
with Release 3 of the NetView program. 


Learning About NetView: Operator Training 
(SK2T-0292) 


NetView Installation and Administration Guide 
(SC31-6018) 


NetView Administration Reference (SC31-6014) 
NetView Tuning Guide (SC31-6079) 

NetView Customization Guide (SC31-6016) 

NetView Customization: Using PLiI and C (SC31-6037) 
NetView Customization: Using Assembler (SC31-6078) 


NetView Customization: Writing Command Lists 
(SC31-6015) 


NetView Operation Primer (SC31-6020) 
NetView Operation (SC31-6019) 
NetView Command Summary (SX75-0026) 


NetView Problem Determination and Diagnosis 
(LY43-0001) 


NetView Problem Determination Supplement for Man- 
agement Services Major Vectors 0001 and 0025 
(LD21-0023) 

NetView Resource Alerts Reference (SC31-6024) 
NetView Storage Estimates (SK2T-1888, a diskette) 


Console Automation Using NetView: Planning 
(SC31-6058) 
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NCP Version 4 Publications 


The following list shows the publications for NCP 
Version 4. 


NCP, SSP, and EP Generation and Loading Guide 
(SC30-3348) 


NCP Migration Guide (SC30-3252) 


NCP, SSP, and EP Resource Definition Guide 
(SC30-3349) 


NCP, SSP, and EP Resource Definition Reference 
(SC30-3254) 


NCP Customization Guide (LY30-5571) 

NCP Customization Reference (LY30-5612) 

SSP Customization (LY43-0021) 

NCP, SSP, and EP Messages and Codes (SC30-3169) 
NCP, SSP, and EP Diagnosis Guide (LY30-5591) 

NCP and EP Reference (LY30-5569) 


NCP and EP Reference Summary and Data Areas 
(LY30-5570) 


NCP Version 5 Publications 


The following list shows the publications for NCP 
Version 5. 


NCP, SSP, and EP Generation and Loading Guide 
(SC30-3348) 


NCP Migration Guide (SC30-3440) 


NCP, SSP, and EP Resource Definition Guide 
(SC30-3447) 


NCP, SSP, and EP Resource Definition Reference 
(SC30-3448) 


NCP Customization Guide (LY30-5606) 

NCP Customization Reference (LY30-5607) 
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